tksbrokerapi.TKSBrokerAPI

   1# -*- coding: utf-8 -*-
   2# Author: Timur Gilmullin
   3
   4"""
   5**TKSBrokerAPI** is the trading platform for automation and simplifying the implementation of trading scenarios,
   6as well as working with Tinkoff Invest API server via the REST protocol. The TKSBrokerAPI platform may be used in two ways:
   7from the console, it has a rich keys and commands, or you can use it as Python module with `python import`.
   8
   9TKSBrokerAPI allows you to automate routine trading operations and implement your trading scenarios, or just receive
  10the necessary information from the broker. It is easy enough to integrate into various CI/CD automation systems.
  11
  12- **Open account for trading:** http://tinkoff.ru/sl/AaX1Et1omnH
  13- **TKSBrokerAPI module documentation:** https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSBrokerAPI.html
  14- **See CLI examples:** https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md#Usage-examples
  15- **Used constants are in the TKSEnums module:** https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSEnums.html
  16- **About Tinkoff Invest API:** https://tinkoff.github.io/investAPI/
  17- **Tinkoff Invest API documentation:** https://tinkoff.github.io/investAPI/swagger-ui/
  18"""
  19
  20# Copyright (c) 2022 Gilmillin Timur Mansurovich
  21#
  22# Licensed under the Apache License, Version 2.0 (the "License");
  23# you may not use this file except in compliance with the License.
  24# You may obtain a copy of the License at
  25#
  26#     http://www.apache.org/licenses/LICENSE-2.0
  27#
  28# Unless required by applicable law or agreed to in writing, software
  29# distributed under the License is distributed on an "AS IS" BASIS,
  30# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31# See the License for the specific language governing permissions and
  32# limitations under the License.
  33
  34
  35import sys
  36import os
  37from argparse import ArgumentParser
  38from importlib.metadata import version
  39
  40from dateutil.tz import tzlocal
  41from time import sleep
  42
  43import re
  44import json
  45import requests
  46import traceback as tb
  47from typing import Union
  48
  49from multiprocessing import cpu_count, Lock
  50from multiprocessing.pool import ThreadPool
  51import pandas as pd
  52
  53from mako.template import Template  # Mako Templates for Python (https://www.makotemplates.org/). Mako is a template library provides simple syntax and maximum performance.
  54from Templates import *  # Some html-templates used by reporting methods in TKSBrokerAPI module
  55from TKSEnums import *  # A lot of constants from enums sections: https://tinkoff.github.io/investAPI/swagger-ui/
  56from TradeRoutines import *  # This library contains some methods used by trade scenarios implemented with TKSBrokerAPI module
  57
  58from pricegenerator.PriceGenerator import PriceGenerator, uLogger  # This module has a lot of instruments to work with candles data (https://github.com/Tim55667757/PriceGenerator)
  59from pricegenerator.UniLogger import DisableLogger as PGDisLog  # Method for disable log from PriceGenerator
  60
  61import UniLogger as uLog  # Logger for TKSBrokerAPI
  62
  63
  64# --- Common technical parameters:
  65
  66PGDisLog(uLogger.handlers[0])  # Disable 3-rd party logging from PriceGenerator
  67uLogger = uLog.UniLogger  # init logger for TKSBrokerAPI
  68uLogger.level = 10  # debug level by default for TKSBrokerAPI module
  69uLogger.handlers[0].level = 20  # info level by default for STDOUT of TKSBrokerAPI module
  70
  71__version__ = "1.6"  # The "major.minor" version setup here, but build number define at the build-server only
  72
  73CPU_COUNT = cpu_count()  # host's real CPU count
  74CPU_USAGES = CPU_COUNT - 1 if CPU_COUNT > 1 else 1  # how many CPUs will be used for parallel calculations
  75
  76
  77class TinkoffBrokerServer:
  78    """
  79    This class implements methods to work with Tinkoff broker server.
  80
  81    Examples to work with API: https://tinkoff.github.io/investAPI/swagger-ui/
  82
  83    About `token`: https://tinkoff.github.io/investAPI/token/
  84    """
  85    def __init__(self, token: str, accountId: str = None, useCache: bool = True, defaultCache: str = "dump.json") -> None:
  86        """
  87        Main class init.
  88
  89        :param token: Bearer token for Tinkoff Invest API. It can be set from environment variable `TKS_API_TOKEN`.
  90        :param accountId: string with numeric user account ID in Tinkoff Broker. It can be found in broker's reports.
  91                          Also, this variable can be set from environment variable `TKS_ACCOUNT_ID`.
  92        :param useCache: use default cache file with raw data to use instead of `iList`.
  93                         True by default. Cache is auto-update if new day has come.
  94                         If you don't want to use cache and always updates raw data then set `useCache=False`.
  95        :param defaultCache: path to default cache file. `dump.json` by default.
  96        """
  97        if token is None or not token:
  98            try:
  99                self.token = r"{}".format(os.environ["TKS_API_TOKEN"])
 100                uLogger.debug("Bearer token for Tinkoff OpenAPI set up from environment variable `TKS_API_TOKEN`. See https://tinkoff.github.io/investAPI/token/")
 101
 102            except KeyError:
 103                uLogger.error("`--token` key or environment variable `TKS_API_TOKEN` is required! See https://tinkoff.github.io/investAPI/token/")
 104                raise Exception("Token required")
 105
 106        else:
 107            self.token = token  # highly priority than environment variable 'TKS_API_TOKEN'
 108            uLogger.debug("Bearer token for Tinkoff OpenAPI set up from class variable `token`")
 109
 110        if accountId is None or not accountId:
 111            try:
 112                self.accountId = r"{}".format(os.environ["TKS_ACCOUNT_ID"])
 113                uLogger.debug("Main account ID [{}] set up from environment variable `TKS_ACCOUNT_ID`".format(self.accountId))
 114
 115            except KeyError:
 116                uLogger.warning("`--account-id` key or environment variable `TKS_ACCOUNT_ID` undefined! Some of operations may be unavailable (overview, trading etc).")
 117
 118        else:
 119            self.accountId = accountId  # highly priority than environment variable 'TKS_ACCOUNT_ID'
 120            uLogger.debug("Main account ID [{}] set up from class variable `accountId`".format(self.accountId))
 121
 122        self.version = __version__  # duplicate here used TKSBrokerAPI main version
 123        """Current TKSBrokerAPI version: major.minor, but the build number define at the build-server only.
 124
 125        Latest version: https://pypi.org/project/tksbrokerapi/
 126        """
 127
 128        self._tag = ""
 129        """Identification TKSBrokerAPI tag in log messages to simplify debugging when platform instances runs in parallel mode. Default: `""` (empty string)."""
 130
 131        self.__lock = Lock()  # initialize multiprocessing mutex lock
 132
 133        self.aliases = TKS_TICKER_ALIASES
 134        """Some aliases instead official tickers.
 135
 136        See also: `TKSEnums.TKS_TICKER_ALIASES`
 137        """
 138
 139        self.aliasesKeys = self.aliases.keys()  # re-calc only first time at class init
 140
 141        self.exclude = TKS_TICKERS_OR_FIGI_EXCLUDED  # some tickers or FIGIs raised exception earlier when it sends to server, that is why we exclude there
 142
 143        self._ticker = ""
 144        """String with ticker, e.g. `GOOGL`. Tickers may be upper case only.
 145
 146        Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc.
 147        More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 148
 149        See also: `SearchByTicker()`, `SearchInstruments()`.
 150        """
 151
 152        self._figi = ""
 153        """String with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`. FIGIs may be upper case only.
 154
 155        See also: `SearchByFIGI()`, `SearchInstruments()`.
 156        """
 157
 158        self.depth = 1
 159        """Depth of Market (DOM) can be >= 1. Default: 1. It used with `--price` key to showing DOM with current prices for givens ticker or FIGI.
 160
 161        See also: `GetCurrentPrices()`.
 162        """
 163
 164        self.server = r"https://invest-public-api.tinkoff.ru/rest"
 165        """Tinkoff REST API server for real trade operations. Default: https://invest-public-api.tinkoff.ru/rest
 166
 167        See also: API method https://tinkoff.github.io/investAPI/#tinkoff-invest-api_1 and `SendAPIRequest()`.
 168        """
 169
 170        uLogger.debug("Broker API server: {}".format(self.server))
 171
 172        self.timeout = 15
 173        """Server operations timeout in seconds. Default: `15`.
 174
 175        See also: `SendAPIRequest()`.
 176        """
 177
 178        self.headers = {
 179            "Content-Type": "application/json",
 180            "accept": "application/json",
 181            "Authorization": "Bearer {}".format(self.token),
 182            "x-app-name": "Tim55667757.TKSBrokerAPI",
 183        }
 184        """
 185        Headers which send in every request to broker server. Please, do not change it!
 186        Default: `{"Content-Type": "application/json", "accept": "application/json", "Authorization": "Bearer {your_token}", "x-app-name": "Tim55667757.TKSBrokerAPI"}`.
 187
 188        See also: `SendAPIRequest()`.
 189        """
 190
 191        self.body = None
 192        """Request body which send to broker server. Default: `None`.
 193
 194        See also: `SendAPIRequest()`.
 195        """
 196
 197        self.moreDebug = False
 198        """Enables more debug information in this class, such as net request and response headers in all methods. `False` by default."""
 199
 200        self.useHTMLReports = False
 201        """
 202        If `True` then TKSBrokerAPI generate also HTML reports from Markdown. `False` by default.
 203        
 204        See also: Mako Templates for Python (https://www.makotemplates.org/). Mako is a template library provides simple syntax and maximum performance.
 205        """
 206
 207        self.historyFile = None
 208        """Full path to the output file where history candles will be saved or updated. Default: `None`, it mean that returns only Pandas DataFrame.
 209
 210        See also: `History()`.
 211        """
 212
 213        self.htmlHistoryFile = "index.html"
 214        """Full path to the html file where rendered candles chart stored. Default: `index.html`.
 215
 216        See also: `ShowHistoryChart()`.
 217        """
 218
 219        self.instrumentsFile = "instruments.md"
 220        """Filename where full available to user instruments list will be saved. Default: `instruments.md`.
 221
 222        See also: `ShowInstrumentsInfo()`.
 223        """
 224
 225        self.searchResultsFile = "search-results.md"
 226        """Filename with all found instruments searched by part of its ticker, FIGI or name. Default: `search-results.md`.
 227
 228        See also: `SearchInstruments()`.
 229        """
 230
 231        self.pricesFile = "prices.md"
 232        """Filename where prices of selected instruments will be saved. Default: `prices.md`.
 233
 234        See also: `GetListOfPrices()`.
 235        """
 236
 237        self.infoFile = "info.md"
 238        """Filename where prices of selected instruments will be saved. Default: `prices.md`.
 239
 240        See also: `ShowInstrumentsInfo()`, `RequestBondCoupons()` and `RequestTradingStatus()`.
 241        """
 242
 243        self.bondsXLSXFile = "ext-bonds.xlsx"
 244        """Filename where wider Pandas DataFrame with more information about bonds: main info, current prices, 
 245        bonds payment calendar, some statistics will be stored. Default: `ext-bonds.xlsx`.
 246
 247        See also: `ExtendBondsData()`.
 248        """
 249
 250        self.calendarFile = "calendar.md"
 251        """Filename where bonds payment calendar will be saved. Default: `calendar.md`.
 252        
 253        Pandas dataframe with only bonds payment calendar also will be stored to default file `calendar.xlsx`.
 254
 255        See also: `CreateBondsCalendar()`, `ShowBondsCalendar()`, `ShowInstrumentInfo()`, `RequestBondCoupons()` and `ExtendBondsData()`.
 256        """
 257
 258        self.overviewFile = "overview.md"
 259        """Filename where current portfolio, open trades and orders will be saved. Default: `overview.md`.
 260
 261        See also: `Overview()`, `RequestPortfolio()`, `RequestPositions()`, `RequestPendingOrders()` and `RequestStopOrders()`.
 262        """
 263
 264        self.overviewDigestFile = "overview-digest.md"
 265        """Filename where short digest of the portfolio status will be saved. Default: `overview-digest.md`.
 266
 267        See also: `Overview()` with parameter `details="digest"`.
 268        """
 269
 270        self.overviewPositionsFile = "overview-positions.md"
 271        """Filename where only open positions, without everything else will be saved. Default: `overview-positions.md`.
 272
 273        See also: `Overview()` with parameter `details="positions"`.
 274        """
 275
 276        self.overviewOrdersFile = "overview-orders.md"
 277        """Filename where open limits and stop orders will be saved. Default: `overview-orders.md`.
 278
 279        See also: `Overview()` with parameter `details="orders"`.
 280        """
 281
 282        self.overviewAnalyticsFile = "overview-analytics.md"
 283        """Filename where only the analytics section and the distribution of the portfolio by various categories will be saved. Default: `overview-analytics.md`.
 284
 285        See also: `Overview()` with parameter `details="analytics"`.
 286        """
 287
 288        self.overviewBondsCalendarFile = "overview-calendar.md"
 289        """Filename where only the bonds calendar section will be saved. Default: `overview-calendar.md`.
 290
 291        See also: `Overview()` with parameter `details="calendar"`.
 292        """
 293
 294        self.reportFile = "deals.md"
 295        """Filename where history of deals and trade statistics will be saved. Default: `deals.md`.
 296
 297        See also: `Deals()`.
 298        """
 299
 300        self.withdrawalLimitsFile = "limits.md"
 301        """Filename where table of funds available for withdrawal will be saved. Default: `limits.md`.
 302
 303        See also: `OverviewLimits()` and `RequestLimits()`.
 304        """
 305
 306        self.userInfoFile = "user-info.md"
 307        """Filename where all available user's data (`accountId`s, common user information, margin status and tariff connections limit) will be saved. Default: `user-info.md`.
 308
 309        See also: `OverviewUserInfo()`, `RequestAccounts()`, `RequestUserInfo()`, `RequestMarginStatus()` and `RequestTariffLimits()`.
 310        """
 311
 312        self.userAccountsFile = "accounts.md"
 313        """Filename where simple table with all available user accounts (`accountId`s) will be saved. Default: `accounts.md`.
 314
 315        See also: `OverviewAccounts()`, `RequestAccounts()`.
 316        """
 317
 318        self.iListDumpFile = "dump.json" if defaultCache is None or not isinstance(defaultCache, str) or not defaultCache else defaultCache
 319        """Filename where raw data about shares, currencies, bonds, etfs and futures will be stored. Default: `dump.json`.
 320
 321        Pandas dataframe with raw instruments data also will be stored to default file `dump.xlsx`.
 322
 323        See also: `DumpInstruments()` and `DumpInstrumentsAsXLSX()`.
 324        """
 325
 326        self.iList = None  # init iList for raw instruments data
 327        """Dictionary with raw data about shares, currencies, bonds, etfs and futures from broker server. Auto-updating and saving dump to the `iListDumpFile`.
 328        
 329        See also: `Listing()`, `DumpInstruments()`.
 330        """
 331
 332        # trying to re-load raw instruments data from file `iListDumpFile` or try to update it from server:
 333        if useCache:
 334            if os.path.exists(self.iListDumpFile):
 335                dumpTime = datetime.fromtimestamp(os.path.getmtime(self.iListDumpFile)).astimezone(tzutc())  # dump modification date and time
 336                curTime = datetime.now(tzutc())
 337
 338                if (curTime.day > dumpTime.day) or (curTime.month > dumpTime.month) or (curTime.year > dumpTime.year):
 339                    uLogger.warning("Local cache may be outdated! It has last modified [{}] UTC. Updating from broker server, wait, please...".format(dumpTime.strftime(TKS_PRINT_DATE_TIME_FORMAT)))
 340
 341                    self.DumpInstruments(forceUpdate=True)  # updating self.iList and dump file
 342
 343                else:
 344                    self.iList = json.load(open(self.iListDumpFile, mode="r", encoding="UTF-8"))  # load iList from dump
 345
 346                    uLogger.debug("Local cache with raw instruments data is used: [{}]. Last modified: [{}] UTC".format(
 347                        os.path.abspath(self.iListDumpFile),
 348                        dumpTime.strftime(TKS_PRINT_DATE_TIME_FORMAT),
 349                    ))
 350
 351            else:
 352                uLogger.warning("Local cache with raw instruments data not exists! Creating new dump, wait, please...")
 353                self.DumpInstruments(forceUpdate=True)  # updating self.iList and creating default dump file
 354
 355        else:
 356            self.iList = self.Listing()  # request new raw instruments data from broker server
 357            self.DumpInstruments(forceUpdate=False)  # save raw instrument's data to default dump file `iListDumpFile`
 358
 359        self.priceModel = PriceGenerator()  # init PriceGenerator object to work with candles data
 360        """PriceGenerator object to work with candles data: load, render interact and non-interact charts and so on.
 361
 362        See also: `LoadHistory()`, `ShowHistoryChart()` and the PriceGenerator project: https://github.com/Tim55667757/PriceGenerator
 363        """
 364
 365    @property
 366    def tag(self) -> str:
 367        """Identification TKSBrokerAPI tag in log messages to simplify debugging when platform instances runs in parallel mode. Default: `""` (empty string)."""
 368        return self._tag
 369
 370    @tag.setter
 371    def tag(self, value):
 372        """Setter for Identification TKSBrokerAPI tag in log messages to simplify debugging when platform instances runs in parallel mode. Default: `""` (empty string)."""
 373        self._tag = str(value)
 374
 375        if self._tag:
 376            for handler in uLogger.handlers:
 377                handler.setFormatter(uLog.logging.Formatter(uLog.formatStringWithTag.format(tag=self._tag)))
 378
 379            uLogger.debug("Custom TKSBrokerAPI tag was set: {}".format(self._tag))
 380
 381        else:
 382            for handler in uLogger.handlers:
 383                handler.setFormatter(uLog.logging.Formatter(uLog.formatString))
 384
 385            uLogger.debug("Default logger format is used")
 386
 387    @property
 388    def ticker(self) -> str:
 389        """String with ticker, e.g. `GOOGL`. Tickers may be upper case only.
 390
 391        Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc.
 392        More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 393
 394        See also: `SearchByTicker()`, `SearchInstruments()`.
 395        """
 396        return self._ticker
 397
 398    @ticker.setter
 399    def ticker(self, value):
 400        """Setter for string with ticker, e.g. `GOOGL`. Tickers may be upper case only.
 401
 402        Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc.
 403        More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 404
 405        See also: `SearchByTicker()`, `SearchInstruments()`.
 406        """
 407        self._ticker = str(value).upper()  # Tickers may be upper case only
 408
 409    @property
 410    def figi(self) -> str:
 411        """String with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`. FIGIs may be upper case only.
 412
 413        See also: `SearchByFIGI()`, `SearchInstruments()`.
 414        """
 415        return self._figi
 416
 417    @figi.setter
 418    def figi(self, value):
 419        """Setter for string with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`. FIGIs may be upper case only.
 420
 421        See also: `SearchByFIGI()`, `SearchInstruments()`.
 422        """
 423        self._figi = str(value).upper()  # FIGI may be upper case only
 424
 425    def _ParseJSON(self, rawData="{}") -> dict:
 426        """
 427        Parse JSON from response string.
 428
 429        :param rawData: this is a string with JSON-formatted text.
 430        :return: JSON (dictionary), parsed from server response string. If an error occurred, then returns empty dict `{}`.
 431        """
 432        try:
 433            responseJSON = json.loads(rawData) if rawData else {}
 434
 435            if self.moreDebug:
 436                uLogger.debug("JSON formatted raw body data of response:\n{}".format(json.dumps(responseJSON, indent=4)))
 437
 438            return responseJSON
 439
 440        except Exception as e:
 441            uLogger.error("An empty dict will be return, because an error occurred in `_ParseJSON()` method with comment: {}".format(e))
 442
 443            return {}
 444
 445    def SendAPIRequest(self, url: str, reqType: str = "GET", retry: int = 3, pause: int = 5) -> dict:
 446        """
 447        Send GET or POST request to broker server and receive JSON object.
 448
 449        self.header: must be defining with dictionary of headers.
 450        self.body: if define then used as request body. None by default.
 451        self.timeout: global request timeout, 15 seconds by default.
 452        :param url: url with REST request.
 453        :param reqType: send "GET" or "POST" request. "GET" by default.
 454        :param retry: how many times retry after first request if an 5xx server errors occurred.
 455        :param pause: sleep time in seconds between retries.
 456        :return: response JSON (dictionary) from broker.
 457        """
 458        if reqType.upper() not in ("GET", "POST"):
 459            uLogger.error("You can define request type: `GET` or `POST`!")
 460            raise Exception("Incorrect value")
 461
 462        if self.moreDebug:
 463            uLogger.debug("Request parameters:")
 464            uLogger.debug("    - REST API URL: {}".format(url))
 465            uLogger.debug("    - request type: {}".format(reqType))
 466            uLogger.debug("    - headers:\n{}".format(str(self.headers).replace(self.token, "*** request token ***")))
 467            uLogger.debug("    - body:\n{}".format(self.body))
 468
 469        # fast hack to avoid all operations with some tickers/FIGI
 470        responseJSON = {}
 471        oK = True
 472        for item in self.exclude:
 473            if item in url:
 474                if self.moreDebug:
 475                    uLogger.warning("Do not execute operations with list of this tickers/FIGI: {}".format(str(self.exclude)))
 476
 477                oK = False
 478                break
 479
 480        if oK:
 481            with self.__lock:  # acquire the mutex lock
 482                counter = 0
 483                response = None
 484                errMsg = ""
 485
 486                while not response and counter <= retry:
 487                    if reqType == "GET":
 488                        response = requests.get(url, headers=self.headers, data=self.body, timeout=self.timeout)
 489
 490                    if reqType == "POST":
 491                        response = requests.post(url, headers=self.headers, data=self.body, timeout=self.timeout)
 492
 493                    if self.moreDebug:
 494                        uLogger.debug("Response:")
 495                        uLogger.debug("    - status code: {}".format(response.status_code))
 496                        uLogger.debug("    - reason: {}".format(response.reason))
 497                        uLogger.debug("    - body length: {}".format(len(response.text)))
 498                        uLogger.debug("    - headers:\n{}".format(response.headers))
 499
 500                    # Server returns some headers:
 501                    # - `x-ratelimit-limit` — shows the settings of the current user limit for this method.
 502                    # - `x-ratelimit-remaining` — the number of remaining requests of this type per minute.
 503                    # - `x-ratelimit-reset` — time in seconds before resetting the request counter.
 504                    # See: https://tinkoff.github.io/investAPI/grpc/#kreya
 505                    if "x-ratelimit-remaining" in response.headers.keys() and response.headers["x-ratelimit-remaining"] == "0":
 506                        rateLimitWait = int(response.headers["x-ratelimit-reset"])
 507                        uLogger.debug("Rate limit exceeded. Waiting {} sec. for reset rate limit and then repeat again...".format(rateLimitWait))
 508                        sleep(rateLimitWait)
 509
 510                    # Error status codes: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
 511                    if 400 <= response.status_code < 500:
 512                        msg = "status code: [{}], response body: {}".format(response.status_code, response.text)
 513                        uLogger.debug("    - not oK, but do not retry for 4xx errors, {}".format(msg))
 514
 515                        if "code" in response.text and "message" in response.text:
 516                            msgDict = self._ParseJSON(rawData=response.text)
 517                            uLogger.warning("HTTP-status code [{}], server message: {}".format(response.status_code, msgDict["message"]))
 518
 519                        counter = retry + 1  # do not retry for 4xx errors
 520
 521                    if 500 <= response.status_code < 600:
 522                        errMsg = "status code: [{}], response body: {}".format(response.status_code, response.text)
 523                        uLogger.debug("    - not oK, {}".format(errMsg))
 524
 525                        if "code" in response.text and "message" in response.text:
 526                            errMsgDict = self._ParseJSON(rawData=response.text)
 527                            uLogger.warning("HTTP-status code [{}], error message: {}".format(response.status_code, errMsgDict["message"]))
 528
 529                        counter += 1
 530
 531                        if counter <= retry:
 532                            uLogger.debug("Retry: [{}]. Wait {} sec. and try again...".format(counter, pause))
 533                            sleep(pause)
 534
 535                responseJSON = self._ParseJSON(rawData=response.text)
 536
 537                if errMsg:
 538                    uLogger.error("Server returns not `oK` status! See: https://tinkoff.github.io/investAPI/errors/")
 539                    uLogger.error("    - not oK, {}".format(errMsg))
 540
 541        return responseJSON
 542
 543    def _IUpdater(self, iType: str) -> tuple:
 544        """
 545        Request instrument by type from server. See available API methods for instruments:
 546        Currencies: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Currencies
 547        Shares: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Shares
 548        Bonds: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Bonds
 549        Etfs: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Etfs
 550        Futures: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Futures
 551
 552        :param iType: type of the instrument, it must be one of supported types in TKS_INSTRUMENTS list.
 553        :return: tuple with iType name and list of available instruments of current type for defined user token.
 554        """
 555        result = []
 556
 557        if iType in TKS_INSTRUMENTS:
 558            uLogger.debug("Requesting available [{}] list. Wait, please...".format(iType))
 559
 560            # all instruments have the same body in API v2 requests:
 561            self.body = str({"instrumentStatus": "INSTRUMENT_STATUS_UNSPECIFIED"})  # Enum: [INSTRUMENT_STATUS_UNSPECIFIED, INSTRUMENT_STATUS_BASE, INSTRUMENT_STATUS_ALL]
 562            instrumentURL = self.server + r"/tinkoff.public.invest.api.contract.v1.InstrumentsService/{}".format(iType)
 563            result = self.SendAPIRequest(instrumentURL, reqType="POST")["instruments"]
 564
 565        return iType, result
 566
 567    def _IWrapper(self, kwargs):
 568        """
 569        Wrapper runs instrument's update method `_IUpdater()`.
 570        It's a workaround for using multiprocessing with kwargs. See: https://stackoverflow.com/a/36799206
 571        """
 572        return self._IUpdater(**kwargs)
 573
 574    def Listing(self) -> dict:
 575        """
 576        Gets JSON with raw data about shares, currencies, bonds, etfs and futures from broker server.
 577
 578        :return: Dictionary with all available broker instruments: currencies, shares, bonds, etfs and futures.
 579        """
 580        uLogger.debug("Requesting all available instruments for current account. Wait, please...")
 581        uLogger.debug("CPU usages for parallel requests: [{}]".format(CPU_USAGES))
 582
 583        # this parameters insert to requests: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService
 584        # iType is type of instrument, it must be one of supported types in TKS_INSTRUMENTS list.
 585        iParams = [{"iType": iType} for iType in TKS_INSTRUMENTS]
 586
 587        poolUpdater = ThreadPool(processes=CPU_USAGES)  # create pool for update instruments in parallel mode
 588        listing = poolUpdater.map(self._IWrapper, iParams)  # execute update operations
 589        poolUpdater.close()  # close the thread pool
 590        poolUpdater.join()  # wait a moment until all data returns from threads
 591
 592        # Dictionary with all broker instruments: shares, currencies, bonds, etfs and futures.
 593        # Next in this code: item[0] is "iType" and item[1] is list of available instruments from the result of _IUpdater() method
 594        iList = {item[0]: {instrument["ticker"]: instrument for instrument in item[1]} for item in listing}
 595
 596        # calculate minimum price increment (step) for all instruments and set up instrument's type:
 597        for iType in iList.keys():
 598            for ticker in iList[iType]:
 599                iList[iType][ticker]["type"] = iType
 600
 601                if "minPriceIncrement" in iList[iType][ticker].keys():
 602                    iList[iType][ticker]["step"] = NanoToFloat(
 603                        iList[iType][ticker]["minPriceIncrement"]["units"],
 604                        iList[iType][ticker]["minPriceIncrement"]["nano"],
 605                    )
 606
 607                else:
 608                    iList[iType][ticker]["step"] = 0  # hack to avoid empty value in some instruments, e.g. futures
 609
 610        return iList
 611
 612    def DumpInstrumentsAsXLSX(self, forceUpdate: bool = False) -> None:
 613        """
 614        Creates XLSX-formatted dump file with raw data of instruments to further used by data scientists or stock analytics.
 615
 616        See also: `DumpInstruments()`, `Listing()`.
 617
 618        :param forceUpdate: if `True` then at first updates data with `Listing()` method,
 619                            otherwise just saves exist `iList` as XLSX-file (default: `dump.xlsx`) .
 620        """
 621        if self.iListDumpFile is None or not self.iListDumpFile:
 622            uLogger.error("Output name of dump file must be defined!")
 623            raise Exception("Filename required")
 624
 625        if not self.iList or forceUpdate:
 626            self.iList = self.Listing()
 627
 628        xlsxDumpFile = self.iListDumpFile.replace(".json", ".xlsx") if self.iListDumpFile.endswith(".json") else self.iListDumpFile + ".xlsx"
 629
 630        # Save as XLSX with separated sheets for every type of instruments:
 631        with pd.ExcelWriter(
 632                path=xlsxDumpFile,
 633                date_format=TKS_DATE_FORMAT,
 634                datetime_format=TKS_DATE_TIME_FORMAT,
 635                mode="w",
 636        ) as writer:
 637            for iType in TKS_INSTRUMENTS:
 638                df = pd.DataFrame.from_dict(data=self.iList[iType], orient="index")  # generate pandas object from self.iList dictionary
 639                df = df[sorted(df)]  # sorted by column names
 640                df = df.applymap(
 641                    lambda item: NanoToFloat(item["units"], item["nano"]) if isinstance(item, dict) and "units" in item.keys() and "nano" in item.keys() else item,
 642                    na_action="ignore",
 643                )  # converting numbers from nano-type to float in every cell
 644                df.to_excel(
 645                    writer,
 646                    sheet_name=iType,
 647                    encoding="UTF-8",
 648                    freeze_panes=(1, 1),
 649                )  # saving as XLSX-file with freeze first row and column as headers
 650
 651        uLogger.info("XLSX-file for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(xlsxDumpFile)))
 652
 653    def DumpInstruments(self, forceUpdate: bool = True) -> str:
 654        """
 655        Receives and returns actual raw data about shares, currencies, bonds, etfs and futures from broker server
 656        using `Listing()` method. If `iListDumpFile` string is not empty then also save information to this file.
 657
 658        See also: `DumpInstrumentsAsXLSX()`, `Listing()`.
 659
 660        :param forceUpdate: if `True` then at first updates data with `Listing()` method,
 661                            otherwise just saves exist `iList` as JSON-file (default: `dump.json`).
 662        :return: serialized JSON formatted `str` with full data of instruments, also saved to the `--output` JSON-file.
 663        """
 664        if self.iListDumpFile is None or not self.iListDumpFile:
 665            uLogger.error("Output name of dump file must be defined!")
 666            raise Exception("Filename required")
 667
 668        if not self.iList or forceUpdate:
 669            self.iList = self.Listing()
 670
 671        jsonDump = json.dumps(self.iList, indent=4, sort_keys=False)  # create JSON object as string
 672        with open(self.iListDumpFile, mode="w", encoding="UTF-8") as fH:
 673            fH.write(jsonDump)
 674
 675        uLogger.info("New cache of instruments data was created: [{}]".format(os.path.abspath(self.iListDumpFile)))
 676
 677        return jsonDump
 678
 679    def ShowInstrumentInfo(self, iJSON: dict, show: bool = True, onlyFiles=False) -> str:
 680        """
 681        Show information about one instrument defined by json data and prints it in Markdown format.
 682
 683        See also: `SearchByTicker()`, `SearchByFIGI()`, `RequestBondCoupons()`, `ExtendBondsData()`, `ShowBondsCalendar()` and `RequestTradingStatus()`.
 684
 685        :param iJSON: json data of instrument, example: `iJSON = self.iList["Shares"][self._ticker]`
 686        :param show: if `True` then also printing information about instrument and its current price.
 687        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
 688        :return: multilines text in Markdown format with information about one instrument.
 689        """
 690        splitLine = "|                                                             |                                                        |\n"
 691        infoText = ""
 692
 693        if iJSON is not None and iJSON and isinstance(iJSON, dict):
 694            info = [
 695                "# Main information\n\n",
 696                "* **Actual on date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
 697                "| Parameters                                                  | Values                                                 |\n",
 698                "|-------------------------------------------------------------|--------------------------------------------------------|\n",
 699                "| Ticker:                                                     | {:<54} |\n".format(iJSON["ticker"]),
 700                "| Full name:                                                  | {:<54} |\n".format(iJSON["name"]),
 701            ]
 702
 703            if "sector" in iJSON.keys() and iJSON["sector"]:
 704                info.append("| Sector:                                                     | {:<54} |\n".format(iJSON["sector"]))
 705
 706            if "countryOfRisk" in iJSON.keys() and iJSON["countryOfRisk"] and "countryOfRiskName" in iJSON.keys() and iJSON["countryOfRiskName"]:
 707                info.append("| Country of instrument:                                      | {:<54} |\n".format("({}) {}".format(iJSON["countryOfRisk"], iJSON["countryOfRiskName"])))
 708
 709            info.extend([
 710                splitLine,
 711                "| FIGI (Financial Instrument Global Identifier):              | {:<54} |\n".format(iJSON["figi"]),
 712                "| Real exchange [Exchange section]:                           | {:<54} |\n".format("{} [{}]".format(TKS_REAL_EXCHANGES[iJSON["realExchange"]], iJSON["exchange"])),
 713            ])
 714
 715            if "isin" in iJSON.keys() and iJSON["isin"]:
 716                info.append("| ISIN (International Securities Identification Number):      | {:<54} |\n".format(iJSON["isin"]))
 717
 718            if "classCode" in iJSON.keys():
 719                info.append("| Class Code (exchange section where instrument is traded):   | {:<54} |\n".format(iJSON["classCode"]))
 720
 721            info.extend([
 722                splitLine,
 723                "| Current broker security trading status:                     | {:<54} |\n".format(TKS_TRADING_STATUSES[iJSON["tradingStatus"]]),
 724                splitLine,
 725                "| Buy operations allowed:                                     | {:<54} |\n".format("Yes" if iJSON["buyAvailableFlag"] else "No"),
 726                "| Sale operations allowed:                                    | {:<54} |\n".format("Yes" if iJSON["sellAvailableFlag"] else "No"),
 727                "| Short positions allowed:                                    | {:<54} |\n".format("Yes" if iJSON["shortEnabledFlag"] else "No"),
 728            ])
 729
 730            if iJSON["figi"]:
 731                self._figi = iJSON["figi"]
 732                iJSON = iJSON | self.RequestTradingStatus()
 733
 734                info.extend([
 735                    splitLine,
 736                    "| Limit orders allowed:                                       | {:<54} |\n".format("Yes" if iJSON["limitOrderAvailableFlag"] else "No"),
 737                    "| Market orders allowed:                                      | {:<54} |\n".format("Yes" if iJSON["marketOrderAvailableFlag"] else "No"),
 738                    "| API trade allowed:                                          | {:<54} |\n".format("Yes" if iJSON["apiTradeAvailableFlag"] else "No"),
 739                ])
 740
 741            info.append(splitLine)
 742
 743            if "type" in iJSON.keys() and iJSON["type"]:
 744                info.append("| Type of the instrument:                                     | {:<54} |\n".format(iJSON["type"]))
 745
 746                if "shareType" in iJSON.keys() and iJSON["shareType"]:
 747                    info.append("| Share type:                                                 | {:<54} |\n".format(TKS_SHARE_TYPES[iJSON["shareType"]]))
 748
 749            if "futuresType" in iJSON.keys() and iJSON["futuresType"]:
 750                info.append("| Futures type:                                               | {:<54} |\n".format(iJSON["futuresType"]))
 751
 752            if "ipoDate" in iJSON.keys() and iJSON["ipoDate"]:
 753                info.append("| IPO date:                                                   | {:<54} |\n".format(iJSON["ipoDate"].replace("T", " ").replace("Z", "")))
 754
 755            if "releasedDate" in iJSON.keys() and iJSON["releasedDate"]:
 756                info.append("| Released date:                                              | {:<54} |\n".format(iJSON["releasedDate"].replace("T", " ").replace("Z", "")))
 757
 758            if "rebalancingFreq" in iJSON.keys() and iJSON["rebalancingFreq"]:
 759                info.append("| Rebalancing frequency:                                      | {:<54} |\n".format(iJSON["rebalancingFreq"]))
 760
 761            if "focusType" in iJSON.keys() and iJSON["focusType"]:
 762                info.append("| Focusing type:                                              | {:<54} |\n".format(iJSON["focusType"]))
 763
 764            if "assetType" in iJSON.keys() and iJSON["assetType"]:
 765                info.append("| Asset type:                                                 | {:<54} |\n".format(iJSON["assetType"]))
 766
 767            if "basicAsset" in iJSON.keys() and iJSON["basicAsset"]:
 768                info.append("| Basic asset:                                                | {:<54} |\n".format(iJSON["basicAsset"]))
 769
 770            if "basicAssetSize" in iJSON.keys() and iJSON["basicAssetSize"]:
 771                info.append("| Basic asset size:                                           | {:<54} |\n".format("{:.2f}".format(NanoToFloat(str(iJSON["basicAssetSize"]["units"]), iJSON["basicAssetSize"]["nano"]))))
 772
 773            if "isoCurrencyName" in iJSON.keys() and iJSON["isoCurrencyName"]:
 774                info.append("| ISO currency name:                                          | {:<54} |\n".format(iJSON["isoCurrencyName"]))
 775
 776            if "currency" in iJSON.keys():
 777                info.append("| Payment currency:                                           | {:<54} |\n".format(iJSON["currency"]))
 778
 779            if iJSON["type"] == "Bonds" and "nominal" in iJSON.keys() and "currency" in iJSON["nominal"].keys():
 780                info.append("| Nominal currency:                                           | {:<54} |\n".format(iJSON["nominal"]["currency"]))
 781
 782            if "firstTradeDate" in iJSON.keys() and iJSON["firstTradeDate"]:
 783                info.append("| First trade date:                                           | {:<54} |\n".format(iJSON["firstTradeDate"].replace("T", " ").replace("Z", "")))
 784
 785            if "lastTradeDate" in iJSON.keys() and iJSON["lastTradeDate"]:
 786                info.append("| Last trade date:                                            | {:<54} |\n".format(iJSON["lastTradeDate"].replace("T", " ").replace("Z", "")))
 787
 788            if "expirationDate" in iJSON.keys() and iJSON["expirationDate"]:
 789                info.append("| Date of expiration:                                         | {:<54} |\n".format(iJSON["expirationDate"].replace("T", " ").replace("Z", "")))
 790
 791            if "stateRegDate" in iJSON.keys() and iJSON["stateRegDate"]:
 792                info.append("| State registration date:                                    | {:<54} |\n".format(iJSON["stateRegDate"].replace("T", " ").replace("Z", "")))
 793
 794            if "placementDate" in iJSON.keys() and iJSON["placementDate"]:
 795                info.append("| Placement date:                                             | {:<54} |\n".format(iJSON["placementDate"].replace("T", " ").replace("Z", "")))
 796
 797            if "maturityDate" in iJSON.keys() and iJSON["maturityDate"]:
 798                info.append("| Maturity date:                                              | {:<54} |\n".format(iJSON["maturityDate"].replace("T", " ").replace("Z", "")))
 799
 800            if "perpetualFlag" in iJSON.keys() and iJSON["perpetualFlag"]:
 801                info.append("| Perpetual bond:                                             | Yes                                                    |\n")
 802
 803            if "otcFlag" in iJSON.keys() and iJSON["otcFlag"]:
 804                info.append("| Over-the-counter (OTC) securities:                          | Yes                                                    |\n")
 805
 806            iExt = None
 807            if iJSON["type"] == "Bonds":
 808                info.extend([
 809                    splitLine,
 810                    "| Bond issue (size / plan):                                   | {:<54} |\n".format("{} / {}".format(iJSON["issueSize"], iJSON["issueSizePlan"])),
 811                    "| Nominal price (100%):                                       | {:<54} |\n".format("{} {}".format(
 812                        "{:.2f}".format(NanoToFloat(str(iJSON["nominal"]["units"]), iJSON["nominal"]["nano"])).rstrip("0").rstrip("."),
 813                        iJSON["nominal"]["currency"],
 814                    )),
 815                ])
 816
 817                if "floatingCouponFlag" in iJSON.keys():
 818                    info.append("| Floating coupon:                                            | {:<54} |\n".format("Yes" if iJSON["floatingCouponFlag"] else "No"))
 819
 820                if "amortizationFlag" in iJSON.keys():
 821                    info.append("| Amortization:                                               | {:<54} |\n".format("Yes" if iJSON["amortizationFlag"] else "No"))
 822
 823                info.append(splitLine)
 824
 825                if "couponQuantityPerYear" in iJSON.keys() and iJSON["couponQuantityPerYear"]:
 826                    info.append("| Number of coupon payments per year:                         | {:<54} |\n".format(iJSON["couponQuantityPerYear"]))
 827
 828                if iJSON["figi"]:
 829                    iExt = self.ExtendBondsData(instruments=iJSON["figi"], xlsx=False)  # extended bonds data
 830
 831                    info.extend([
 832                        "| Days last to maturity date:                                 | {:<54} |\n".format(iExt["daysToMaturity"][0]),
 833                        "| Coupons yield (average coupon daily yield * 365):           | {:<54} |\n".format("{:.2f}%".format(iExt["couponsYield"][0])),
 834                        "| Current price yield (average daily yield * 365):            | {:<54} |\n".format("{:.2f}%".format(iExt["currentYield"][0])),
 835                    ])
 836
 837                if "aciValue" in iJSON.keys() and iJSON["aciValue"]:
 838                    info.append("| Current accumulated coupon income (ACI):                    | {:<54} |\n".format("{:.2f} {}".format(
 839                        NanoToFloat(str(iJSON["aciValue"]["units"]), iJSON["aciValue"]["nano"]),
 840                        iJSON["aciValue"]["currency"]
 841                    )))
 842
 843            if "currentPrice" in iJSON.keys():
 844                info.append(splitLine)
 845
 846                currency = iJSON["currency"] if "currency" in iJSON.keys() else ""  # nominal currency for bonds, otherwise currency of instrument
 847                aciCurrency = iExt["aciCurrency"][0] if iJSON["type"] == "Bonds" and iExt is not None and "aciCurrency" in iExt.keys() else ""  # payment currency
 848
 849                bondPrevClose = iExt["closePrice"][0] if iJSON["type"] == "Bonds" and iExt is not None and "closePrice" in iExt.keys() else 0  # previous close price of bond
 850                bondLastPrice = iExt["lastPrice"][0] if iJSON["type"] == "Bonds" and iExt is not None and "lastPrice" in iExt.keys() else 0  # last price of bond
 851                bondLimitUp = iExt["limitUp"][0] if iJSON["type"] == "Bonds" and iExt is not None and "limitUp" in iExt.keys() else 0  # max price of bond
 852                bondLimitDown = iExt["limitDown"][0] if iJSON["type"] == "Bonds" and iExt is not None and "limitDown" in iExt.keys() else 0  # min price of bond
 853                bondChangesDelta = iExt["changesDelta"][0] if iJSON["type"] == "Bonds" and iExt is not None and "changesDelta" in iExt.keys() else 0  # delta between last deal price and last close
 854
 855                curPriceSell = iJSON["currentPrice"]["sell"][0]["price"] if iJSON["currentPrice"]["sell"] else 0
 856                curPriceBuy = iJSON["currentPrice"]["buy"][0]["price"] if iJSON["currentPrice"]["buy"] else 0
 857
 858                info.extend([
 859                    "| Previous close price of the instrument:                     | {:<54} |\n".format("{}{}".format(
 860                        "{}".format(iJSON["currentPrice"]["closePrice"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["closePrice"] is not None else "N/A",
 861                        "% of nominal price ({:.2f} {})".format(bondPrevClose, aciCurrency) if iJSON["type"] == "Bonds" else " {}".format(currency),
 862                    )),
 863                    "| Last deal price of the instrument:                          | {:<54} |\n".format("{}{}".format(
 864                        "{}".format(iJSON["currentPrice"]["lastPrice"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["lastPrice"] is not None else "N/A",
 865                        "% of nominal price ({:.2f} {})".format(bondLastPrice, aciCurrency) if iJSON["type"] == "Bonds" else " {}".format(currency),
 866                    )),
 867                    "| Changes between last deal price and last close              | {:<54} |\n".format(
 868                        "{:.2f}%{}".format(
 869                            iJSON["currentPrice"]["changes"],
 870                            " ({}{:.2f} {})".format(
 871                                "+" if bondChangesDelta > 0 else "",
 872                                bondChangesDelta,
 873                                aciCurrency
 874                            ) if iJSON["type"] == "Bonds" else " ({}{:.2f} {})".format(
 875                                "+" if iJSON["currentPrice"]["lastPrice"] > iJSON["currentPrice"]["closePrice"] else "",
 876                                iJSON["currentPrice"]["lastPrice"] - iJSON["currentPrice"]["closePrice"],
 877                                currency
 878                            ),
 879                        )
 880                    ),
 881                    "| Current limit price, min / max:                             | {:<54} |\n".format("{}{} / {}{}{}".format(
 882                        "{}".format(iJSON["currentPrice"]["limitDown"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["limitDown"] is not None else "N/A",
 883                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 884                        "{}".format(iJSON["currentPrice"]["limitUp"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["limitUp"] is not None else "N/A",
 885                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 886                        " ({:.2f} {} / {:.2f} {})".format(bondLimitDown, aciCurrency, bondLimitUp, aciCurrency) if iJSON["type"] == "Bonds" else ""
 887                    )),
 888                    "| Actual price, sell / buy:                                   | {:<54} |\n".format("{}{} / {}{}{}".format(
 889                        "{}".format(curPriceSell).rstrip("0").rstrip(".") if curPriceSell != 0 else "N/A",
 890                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 891                        "{}".format(curPriceBuy).rstrip("0").rstrip(".") if curPriceBuy != 0 else "N/A",
 892                        "%" if iJSON["type"] == "Bonds" else" {}".format(currency),
 893                        " ({:.2f} {} / {:.2f} {})".format(curPriceSell, aciCurrency, curPriceBuy, aciCurrency) if iJSON["type"] == "Bonds" else ""
 894                    )),
 895                ])
 896
 897            if "lot" in iJSON.keys():
 898                info.append("| Minimum lot to buy:                                         | {:<54} |\n".format(iJSON["lot"]))
 899
 900            if "step" in iJSON.keys() and iJSON["step"] != 0:
 901                info.append("| Minimum price increment (step):                             | {:<54} |\n".format("{} {}".format(iJSON["step"], iJSON["currency"] if "currency" in iJSON.keys() else "")))
 902
 903            # Add bond payment calendar:
 904            if iJSON["type"] == "Bonds":
 905                strCalendar = self.ShowBondsCalendar(extBonds=iExt, show=False)   # bond payment calendar
 906                info.extend(["\n#", strCalendar])
 907
 908            infoText += "".join(info)
 909
 910            if show and not onlyFiles:
 911                uLogger.info("{}".format(infoText))
 912
 913            if self.infoFile is not None and (show or onlyFiles):
 914                with open(self.infoFile, "w", encoding="UTF-8") as fH:
 915                    fH.write(infoText)
 916
 917                uLogger.info("Info about instrument with ticker [{}] and FIGI [{}] was saved to file: [{}]".format(iJSON["ticker"], iJSON["figi"], os.path.abspath(self.infoFile)))
 918
 919                if self.useHTMLReports:
 920                    htmlFilePath = self.infoFile.replace(".md", ".html") if self.infoFile.endswith(".md") else self.infoFile + ".html"
 921                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
 922                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Main information", commonCSS=COMMON_CSS, markdown=infoText))
 923
 924                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
 925
 926        return infoText
 927
 928    def SearchByTicker(self, requestPrice: bool = False, show: bool = False) -> dict:
 929        """
 930        Search and return raw broker's information about instrument by its ticker. Variable `ticker` must be defined!
 931
 932        :param requestPrice: if `False` then do not request current price of instrument (because this is long operation).
 933        :param show: if `False` then do not run `ShowInstrumentInfo()` method and do not print info to the console.
 934        :return: JSON formatted data with information about instrument.
 935        """
 936        tickerJSON = {}
 937        if self.moreDebug:
 938            uLogger.debug("Searching information about instrument by it's ticker [{}] ...".format(self._ticker))
 939
 940        if not self._ticker:
 941            uLogger.warning("self._ticker variable is not be empty!")
 942
 943        else:
 944            if self._ticker in TKS_TICKERS_OR_FIGI_EXCLUDED:
 945                uLogger.warning("Instrument with ticker [{}] not allowed for trading!".format(self._ticker))
 946                raise Exception("Instrument not allowed")
 947
 948            if not self.iList:
 949                self.iList = self.Listing()
 950
 951            if self._ticker in self.iList["Shares"].keys():
 952                tickerJSON = self.iList["Shares"][self._ticker]
 953                if self.moreDebug:
 954                    uLogger.debug("Ticker [{}] found in shares list".format(self._ticker))
 955
 956            elif self._ticker in self.iList["Currencies"].keys():
 957                tickerJSON = self.iList["Currencies"][self._ticker]
 958                if self.moreDebug:
 959                    uLogger.debug("Ticker [{}] found in currencies list".format(self._ticker))
 960
 961            elif self._ticker in self.iList["Bonds"].keys():
 962                tickerJSON = self.iList["Bonds"][self._ticker]
 963                if self.moreDebug:
 964                    uLogger.debug("Ticker [{}] found in bonds list".format(self._ticker))
 965
 966            elif self._ticker in self.iList["Etfs"].keys():
 967                tickerJSON = self.iList["Etfs"][self._ticker]
 968                if self.moreDebug:
 969                    uLogger.debug("Ticker [{}] found in etfs list".format(self._ticker))
 970
 971            elif self._ticker in self.iList["Futures"].keys():
 972                tickerJSON = self.iList["Futures"][self._ticker]
 973                if self.moreDebug:
 974                    uLogger.debug("Ticker [{}] found in futures list".format(self._ticker))
 975
 976        if tickerJSON:
 977            self._figi = tickerJSON["figi"]
 978
 979            if requestPrice:
 980                tickerJSON["currentPrice"] = self.GetCurrentPrices(show=False)
 981
 982                if tickerJSON["currentPrice"]["closePrice"] is not None and tickerJSON["currentPrice"]["closePrice"] != 0 and tickerJSON["currentPrice"]["lastPrice"] is not None:
 983                    tickerJSON["currentPrice"]["changes"] = 100 * (tickerJSON["currentPrice"]["lastPrice"] - tickerJSON["currentPrice"]["closePrice"]) / tickerJSON["currentPrice"]["closePrice"]
 984
 985                else:
 986                    tickerJSON["currentPrice"]["changes"] = 0
 987
 988            if show:
 989                self.ShowInstrumentInfo(iJSON=tickerJSON, show=True)  # print info as Markdown text
 990
 991        else:
 992            if show:
 993                uLogger.warning("Ticker [{}] not found in available broker instrument's list!".format(self._ticker))
 994
 995        return tickerJSON
 996
 997    def SearchByFIGI(self, requestPrice: bool = False, show: bool = False) -> dict:
 998        """
 999        Search and return raw broker's information about instrument by its FIGI. Variable `figi` must be defined!
1000
1001        :param requestPrice: if `False` then do not request current price of instrument (it's long operation).
1002        :param show: if `False` then do not run `ShowInstrumentInfo()` method and do not print info to the console.
1003        :return: JSON formatted data with information about instrument.
1004        """
1005        figiJSON = {}
1006        if self.moreDebug:
1007            uLogger.debug("Searching information about instrument by it's FIGI [{}] ...".format(self._figi))
1008
1009        if not self._figi:
1010            uLogger.warning("self._figi variable is not be empty!")
1011
1012        else:
1013            if self._figi in TKS_TICKERS_OR_FIGI_EXCLUDED:
1014                uLogger.warning("Instrument with figi [{}] not allowed for trading!".format(self._figi))
1015                raise Exception("Instrument not allowed")
1016
1017            if not self.iList:
1018                self.iList = self.Listing()
1019
1020            for item in self.iList["Shares"].keys():
1021                if self._figi == self.iList["Shares"][item]["figi"]:
1022                    figiJSON = self.iList["Shares"][item]
1023
1024                    if self.moreDebug:
1025                        uLogger.debug("FIGI [{}] found in shares list".format(self._figi))
1026
1027                    break
1028
1029            if not figiJSON:
1030                for item in self.iList["Currencies"].keys():
1031                    if self._figi == self.iList["Currencies"][item]["figi"]:
1032                        figiJSON = self.iList["Currencies"][item]
1033
1034                        if self.moreDebug:
1035                            uLogger.debug("FIGI [{}] found in currencies list".format(self._figi))
1036
1037                        break
1038
1039            if not figiJSON:
1040                for item in self.iList["Bonds"].keys():
1041                    if self._figi == self.iList["Bonds"][item]["figi"]:
1042                        figiJSON = self.iList["Bonds"][item]
1043
1044                        if self.moreDebug:
1045                            uLogger.debug("FIGI [{}] found in bonds list".format(self._figi))
1046
1047                        break
1048
1049            if not figiJSON:
1050                for item in self.iList["Etfs"].keys():
1051                    if self._figi == self.iList["Etfs"][item]["figi"]:
1052                        figiJSON = self.iList["Etfs"][item]
1053
1054                        if self.moreDebug:
1055                            uLogger.debug("FIGI [{}] found in etfs list".format(self._figi))
1056
1057                        break
1058
1059            if not figiJSON:
1060                for item in self.iList["Futures"].keys():
1061                    if self._figi == self.iList["Futures"][item]["figi"]:
1062                        figiJSON = self.iList["Futures"][item]
1063
1064                        if self.moreDebug:
1065                            uLogger.debug("FIGI [{}] found in futures list".format(self._figi))
1066
1067                        break
1068
1069        if figiJSON:
1070            self._figi = figiJSON["figi"]
1071            self._ticker = figiJSON["ticker"]
1072
1073            if requestPrice:
1074                figiJSON["currentPrice"] = self.GetCurrentPrices(show=False)
1075
1076                if figiJSON["currentPrice"]["closePrice"] is not None and figiJSON["currentPrice"]["closePrice"] != 0 and figiJSON["currentPrice"]["lastPrice"] is not None:
1077                    figiJSON["currentPrice"]["changes"] = 100 * (figiJSON["currentPrice"]["lastPrice"] - figiJSON["currentPrice"]["closePrice"]) / figiJSON["currentPrice"]["closePrice"]
1078
1079                else:
1080                    figiJSON["currentPrice"]["changes"] = 0
1081
1082            if show:
1083                self.ShowInstrumentInfo(iJSON=figiJSON, show=True)  # print info as Markdown text
1084
1085        else:
1086            if show:
1087                uLogger.warning("FIGI [{}] not found in available broker instrument's list!".format(self._figi))
1088
1089        return figiJSON
1090
1091    def GetCurrentPrices(self, show: bool = True) -> dict:
1092        """
1093        Get and show Depth of Market with current prices of the instrument as dictionary. Result example with `depth` 5:
1094        `{"buy": [{"price": 1243.8, "quantity": 193},
1095                  {"price": 1244.0, "quantity": 168},
1096                  {"price": 1244.8, "quantity": 5},
1097                  {"price": 1245.0, "quantity": 61},
1098                  {"price": 1245.4, "quantity": 60}],
1099          "sell": [{"price": 1243.6, "quantity": 8},
1100                   {"price": 1242.6, "quantity": 10},
1101                   {"price": 1242.4, "quantity": 18},
1102                   {"price": 1242.2, "quantity": 50},
1103                   {"price": 1242.0, "quantity": 113}],
1104          "limitUp": 1619.0, "limitDown": 903.4, "lastPrice": 1243.8, "closePrice": 1263.0}`, where parameters mean:
1105        - buy: list of dicts with Sellers prices, see also: https://tinkoff.github.io/investAPI/marketdata/#order
1106        - sell: list of dicts with Buyers prices,
1107            - price: price of 1 instrument (to get the cost of the lot, you need to multiply it by the lot of size of the instrument),
1108            - quantity: volume value by current price in lots,
1109        - limitUp: current trade session limit price, maximum,
1110        - limitDown: current trade session limit price, minimum,
1111        - lastPrice: last deal price of the instrument,
1112        - closePrice: previous trade session close price of the instrument.
1113
1114        See also: `SearchByTicker()` and `SearchByFIGI()`.
1115        REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetOrderBook
1116        Response fields: https://tinkoff.github.io/investAPI/marketdata/#getorderbookresponse
1117
1118        :param show: if `True` then print DOM to log and console.
1119        :return: orders book dict with lists of current buy and sell prices: `{"buy": [{"price": x1, "quantity": y1, ...}], "sell": [....]}`.
1120                 If an error occurred then returns an empty record:
1121                 `{"buy": [], "sell": [], "limitUp": None, "limitDown": None, "lastPrice": None, "closePrice": None}`.
1122        """
1123        prices = {"buy": [], "sell": [], "limitUp": 0, "limitDown": 0, "lastPrice": 0, "closePrice": 0}
1124
1125        if self.depth < 1:
1126            uLogger.error("Depth of Market (DOM) must be >=1!")
1127            raise Exception("Incorrect value")
1128
1129        if not (self._ticker or self._figi):
1130            uLogger.error("self._ticker or self._figi variables must be defined!")
1131            raise Exception("Ticker or FIGI required")
1132
1133        if self._ticker and not self._figi:
1134            instrumentByTicker = self.SearchByTicker(requestPrice=False)  # WARNING! requestPrice=False to avoid recursion!
1135            self._figi = instrumentByTicker["figi"] if instrumentByTicker else ""
1136
1137        if not self._ticker and self._figi:
1138            instrumentByFigi = self.SearchByFIGI(requestPrice=False)  # WARNING! requestPrice=False to avoid recursion!
1139            self._ticker = instrumentByFigi["ticker"] if instrumentByFigi else ""
1140
1141        if not self._figi:
1142            uLogger.error("FIGI is not defined!")
1143            raise Exception("Ticker or FIGI required")
1144
1145        else:
1146            uLogger.debug("Requesting current prices: ticker [{}], FIGI [{}]. Wait, please...".format(self._ticker, self._figi))
1147
1148            # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetOrderBook
1149            priceURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetOrderBook"
1150            self.body = str({"figi": self._figi, "depth": self.depth})
1151            pricesResponse = self.SendAPIRequest(priceURL, reqType="POST")  # Response fields: https://tinkoff.github.io/investAPI/marketdata/#getorderbookresponse
1152
1153            if pricesResponse and not ("code" in pricesResponse.keys() or "message" in pricesResponse.keys() or "description" in pricesResponse.keys()):
1154                # list of dicts with sellers orders:
1155                prices["buy"] = [{"price": round(NanoToFloat(item["price"]["units"], item["price"]["nano"]), 6), "quantity": int(item["quantity"])} for item in pricesResponse["asks"]]
1156
1157                # list of dicts with buyers orders:
1158                prices["sell"] = [{"price": round(NanoToFloat(item["price"]["units"], item["price"]["nano"]), 6), "quantity": int(item["quantity"])} for item in pricesResponse["bids"]]
1159
1160                # max price of instrument at this time:
1161                prices["limitUp"] = round(NanoToFloat(pricesResponse["limitUp"]["units"], pricesResponse["limitUp"]["nano"]), 6) if "limitUp" in pricesResponse.keys() else None
1162
1163                # min price of instrument at this time:
1164                prices["limitDown"] = round(NanoToFloat(pricesResponse["limitDown"]["units"], pricesResponse["limitDown"]["nano"]), 6) if "limitDown" in pricesResponse.keys() else None
1165
1166                # last price of deal with instrument:
1167                prices["lastPrice"] = round(NanoToFloat(pricesResponse["lastPrice"]["units"], pricesResponse["lastPrice"]["nano"]), 6) if "lastPrice" in pricesResponse.keys() else 0
1168
1169                # last close price of instrument:
1170                prices["closePrice"] = round(NanoToFloat(pricesResponse["closePrice"]["units"], pricesResponse["closePrice"]["nano"]), 6) if "closePrice" in pricesResponse.keys() else 0
1171
1172            else:
1173                uLogger.warning("Server return an empty or error response! See full log. Instrument: ticker [{}], FIGI [{}]".format(self._ticker, self._figi))
1174                uLogger.debug("Server response: {}".format(pricesResponse))
1175
1176            if show:
1177                if prices["buy"] or prices["sell"]:
1178                    info = [
1179                        "Orders book actual at [{}] (UTC)\nTicker: [{}], FIGI: [{}], Depth of Market: [{}]\n".format(
1180                            datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
1181                            self._ticker,
1182                            self._figi,
1183                            self.depth,
1184                        ),
1185                        "-" * 60, "\n",
1186                        "             Orders of Buyers | Orders of Sellers\n",
1187                        "-" * 60, "\n",
1188                        "        Sell prices (volumes) | Buy prices (volumes)\n",
1189                        "-" * 60, "\n",
1190                    ]
1191
1192                    if not prices["buy"]:
1193                        info.append("                              | No orders!\n")
1194                        sumBuy = 0
1195
1196                    else:
1197                        sumBuy = sum([x["quantity"] for x in prices["buy"]])
1198                        maxMinSorted = sorted(prices["buy"], key=lambda k: k["price"], reverse=True)
1199                        for item in maxMinSorted:
1200                            info.append("                              | {} ({})\n".format(item["price"], item["quantity"]))
1201
1202                    if not prices["sell"]:
1203                        info.append("No orders!                    |\n")
1204                        sumSell = 0
1205
1206                    else:
1207                        sumSell = sum([x["quantity"] for x in prices["sell"]])
1208                        for item in prices["sell"]:
1209                            info.append("{:>29} |\n".format("{} ({})".format(item["price"], item["quantity"])))
1210
1211                    info.extend([
1212                        "-" * 60, "\n",
1213                        "{:>29} | {}\n".format("Total sell: {}".format(sumSell), "Total buy: {}".format(sumBuy)),
1214                        "-" * 60, "\n",
1215                    ])
1216
1217                    infoText = "".join(info)
1218
1219                    uLogger.info("Current prices in order book:\n\n{}".format(infoText))
1220
1221                else:
1222                    uLogger.warning("Orders book is empty at this time! Instrument: ticker [{}], FIGI [{}]".format(self._ticker, self._figi))
1223
1224        return prices
1225
1226    def ShowInstrumentsInfo(self, show: bool = True, onlyFiles=False) -> str:
1227        """
1228        This method get and show information about all available broker instruments for current user account.
1229        If `instrumentsFile` string is not empty then also save information to this file.
1230
1231        :param show: if `True` then print results to console, if `False` — print only to file.
1232        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
1233        :return: multi-lines string with all available broker instruments.
1234        """
1235        if not self.iList:
1236            self.iList = self.Listing()
1237
1238        info = [
1239            "# All available instruments from Tinkoff Broker server for current user token\n\n",
1240            "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
1241        ]
1242
1243        # add instruments count by type:
1244        for iType in self.iList.keys():
1245            info.append("* **{}:** [{}]\n".format(iType, len(self.iList[iType])))
1246
1247        headerLine = "| Ticker       | Full name                                                 | FIGI         | Cur | Lot     | Step       |\n"
1248        splitLine = "|--------------|-----------------------------------------------------------|--------------|-----|---------|------------|\n"
1249
1250        # generating info tables with all instruments by type:
1251        for iType in self.iList.keys():
1252            info.extend(["\n\n## {} available. Total: [{}]\n\n".format(iType, len(self.iList[iType])), headerLine, splitLine])
1253
1254            for instrument in self.iList[iType].keys():
1255                iName = self.iList[iType][instrument]["name"]  # instrument's name
1256                if len(iName) > 57:
1257                    iName = "{}...".format(iName[:54])  # right trim for a long string
1258
1259                info.append("| {:<12} | {:<57} | {:<12} | {:<3} | {:<7} | {:<10} |\n".format(
1260                    self.iList[iType][instrument]["ticker"],
1261                    iName,
1262                    self.iList[iType][instrument]["figi"],
1263                    self.iList[iType][instrument]["currency"],
1264                    self.iList[iType][instrument]["lot"],
1265                    "{:.10f}".format(self.iList[iType][instrument]["step"]).rstrip("0").rstrip(".") if self.iList[iType][instrument]["step"] > 0 else 0,
1266                ))
1267
1268        infoText = "".join(info)
1269
1270        if show and not onlyFiles:
1271            uLogger.info(infoText)
1272
1273        if self.instrumentsFile and (show or onlyFiles):
1274            with open(self.instrumentsFile, "w", encoding="UTF-8") as fH:
1275                fH.write(infoText)
1276
1277            uLogger.info("All available instruments are saved to file: [{}]".format(os.path.abspath(self.instrumentsFile)))
1278
1279            if self.useHTMLReports:
1280                htmlFilePath = self.instrumentsFile.replace(".md", ".html") if self.instrumentsFile.endswith(".md") else self.instrumentsFile + ".html"
1281                with open(htmlFilePath, "w", encoding="UTF-8") as fH:
1282                    fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="List of instruments", commonCSS=COMMON_CSS, markdown=infoText))
1283
1284                uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
1285
1286        return infoText
1287
1288    def SearchInstruments(self, pattern: str, show: bool = True, onlyFiles=False) -> dict:
1289        """
1290        This method search and show information about instruments by part of its ticker, FIGI or name.
1291        If `searchResultsFile` string is not empty then also save information to this file.
1292
1293        :param pattern: string with part of ticker, FIGI or instrument's name.
1294        :param show: if `True` then print results to console, if `False` — return list of result only.
1295        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
1296        :return: list of dictionaries with all found instruments.
1297        """
1298        if not self.iList:
1299            self.iList = self.Listing()
1300
1301        searchResults = {iType: {} for iType in self.iList}  # same as iList but will contain only filtered instruments
1302        compiledPattern = re.compile(pattern, re.IGNORECASE)
1303
1304        for iType in self.iList:
1305            for instrument in self.iList[iType].values():
1306                searchResult = compiledPattern.search(" ".join(
1307                    [instrument["ticker"], instrument["figi"], instrument["name"]]
1308                ))
1309
1310                if searchResult:
1311                    searchResults[iType][instrument["ticker"]] = instrument
1312
1313        resultsLen = sum([len(searchResults[iType]) for iType in searchResults])
1314        info = [
1315            "# Search results\n\n",
1316            "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
1317            "* **Search pattern:** [{}]\n".format(pattern),
1318            "* **Found instruments:** [{}]\n\n".format(resultsLen),
1319            '**Note:** you can view info about found instruments with key "--info", e.g.: "tksbrokerapi -t TICKER --info" or "tksbrokerapi -f FIGI --info".\n'
1320        ]
1321        infoShort = info[:]
1322
1323        headerLine = "| Type       | Ticker       | Full name                                                      | FIGI         |\n"
1324        splitLine = "|------------|--------------|----------------------------------------------------------------|--------------|\n"
1325        skippedLine = "| ...        | ...          | ...                                                            | ...          |\n"
1326
1327        if resultsLen == 0:
1328            info.append("\nNo results\n")
1329            infoShort.append("\nNo results\n")
1330            uLogger.warning("No results. Try changing your search pattern.")
1331
1332        else:
1333            for iType in searchResults:
1334                iTypeValuesCount = len(searchResults[iType].values())
1335                if iTypeValuesCount > 0:
1336                    info.extend(["\n## {}: [{}]\n\n".format(iType, iTypeValuesCount), headerLine, splitLine])
1337                    infoShort.extend(["\n### {}: [{}]\n\n".format(iType, iTypeValuesCount), headerLine, splitLine])
1338
1339                    for instrument in searchResults[iType].values():
1340                        info.append("| {:<10} | {:<12} | {:<63}| {:<13}|\n".format(
1341                            instrument["type"],
1342                            instrument["ticker"],
1343                            "{}...".format(instrument["name"][:60]) if len(instrument["name"]) > 63 else instrument["name"],  # right trim for a long string
1344                            instrument["figi"],
1345                        ))
1346
1347                    if iTypeValuesCount <= 5:
1348                        infoShort.extend(info[-iTypeValuesCount:])
1349
1350                    else:
1351                        infoShort.extend(info[-5:])
1352                        infoShort.append(skippedLine)
1353
1354        infoText = "".join(info)
1355        infoTextShort = "".join(infoShort)
1356
1357        if show and not onlyFiles:
1358            uLogger.info(infoTextShort)
1359            uLogger.info("You can view info about found instruments with key `--info`, e.g.: `tksbrokerapi -t IBM --info` or `tksbrokerapi -f BBG000BLNNH6 --info`")
1360
1361        if self.searchResultsFile and (show or onlyFiles):
1362            with open(self.searchResultsFile, "w", encoding="UTF-8") as fH:
1363                fH.write(infoText)
1364
1365            uLogger.info("Full search results were saved to file: [{}]".format(os.path.abspath(self.searchResultsFile)))
1366
1367            if self.useHTMLReports:
1368                htmlFilePath = self.searchResultsFile.replace(".md", ".html") if self.searchResultsFile.endswith(".md") else self.searchResultsFile + ".html"
1369                with open(htmlFilePath, "w", encoding="UTF-8") as fH:
1370                    fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Search results", commonCSS=COMMON_CSS, markdown=infoText))
1371
1372                uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
1373
1374        return searchResults
1375
1376    def GetUniqueFIGIs(self, instruments: list[str]) -> list:
1377        """
1378        Creating list with unique instrument FIGIs from input list of tickers (priority) or FIGIs.
1379
1380        :param instruments: list of strings with tickers or FIGIs.
1381        :return: list with unique instrument FIGIs only.
1382        """
1383        requestedInstruments = []
1384        for iName in instruments:
1385            if iName not in self.aliases.keys():
1386                if iName not in requestedInstruments:
1387                    requestedInstruments.append(iName)
1388
1389            else:
1390                if iName not in requestedInstruments:
1391                    if self.aliases[iName] not in requestedInstruments:
1392                        requestedInstruments.append(self.aliases[iName])
1393
1394        uLogger.debug("Requested instruments without duplicates of tickers or FIGIs: {}".format(requestedInstruments))
1395
1396        onlyUniqueFIGIs = []
1397        for iName in requestedInstruments:
1398            if iName in TKS_TICKERS_OR_FIGI_EXCLUDED:
1399                continue
1400
1401            self._ticker = iName
1402            iData = self.SearchByTicker(requestPrice=False)  # trying to find instrument by ticker
1403
1404            if not iData:
1405                self._ticker = ""
1406                self._figi = iName
1407
1408                iData = self.SearchByFIGI(requestPrice=False)  # trying to find instrument by FIGI
1409
1410                if not iData:
1411                    self._figi = ""
1412                    uLogger.warning("Instrument [{}] not in list of available instruments for current token!".format(iName))
1413
1414            if iData and iData["figi"] not in onlyUniqueFIGIs:
1415                onlyUniqueFIGIs.append(iData["figi"])
1416
1417        uLogger.debug("Unique list of FIGIs: {}".format(onlyUniqueFIGIs))
1418
1419        return onlyUniqueFIGIs
1420
1421    def GetListOfPrices(self, instruments: list[str], show: bool = False, onlyFiles=False) -> list[dict]:
1422        """
1423        This method get, maybe show and return prices of list of instruments. WARNING! This is potential long operation!
1424
1425        See limits: https://tinkoff.github.io/investAPI/limits/
1426
1427        If `pricesFile` string is not empty then also save information to this file.
1428
1429        :param instruments: list of strings with tickers or FIGIs.
1430        :param show: if `True` then prints prices to console, if `False` — prints only to file `pricesFile`.
1431        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
1432        :return: list of instruments looks like `[{some ticker info, "currentPrice": {current prices}}, {...}, ...]`.
1433                 One item is dict returned by `SearchByTicker()` or `SearchByFIGI()` methods.
1434        """
1435        if instruments is None or not instruments:
1436            uLogger.error("You must define some of tickers or FIGIs to request it's actual prices!")
1437            raise Exception("Ticker or FIGI required")
1438
1439        onlyUniqueFIGIs = self.GetUniqueFIGIs(instruments)
1440
1441        uLogger.debug("Requesting current prices from Tinkoff Broker server...")
1442
1443        iList = []  # trying to get info and current prices about all unique instruments:
1444        for self._figi in onlyUniqueFIGIs:
1445            iData = self.SearchByFIGI(requestPrice=True, show=False)
1446            iList.append(iData)
1447
1448        self.ShowListOfPrices(iList, show, onlyFiles)
1449
1450        return iList
1451
1452    def ShowListOfPrices(self, iList: list, show: bool = True, onlyFiles=False) -> str:
1453        """
1454        Show table contains current prices of given instruments.
1455
1456        :param iList: list of instruments looks like `[{some ticker info, "currentPrice": {current prices}}, {...}, ...]`.
1457                      One item is dict returned by `SearchByTicker(requestPrice=True)` or by `SearchByFIGI(requestPrice=True)` methods.
1458        :param show: if `True` then prints prices to console, if `False` — prints only to file `pricesFile`.
1459        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
1460        :return: multilines text in Markdown format as a table contains current prices.
1461        """
1462        infoText = ""
1463
1464        if show or self.pricesFile or onlyFiles:
1465            info = [
1466                "# Current prices\n\n* **Actual on date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime("%Y-%m-%d %H:%M")),
1467                "| Ticker       | FIGI         | Type       | Prev. close | Last price  | Chg. %   | Day limits min/max  | Actual sell / buy   | Curr. |\n",
1468                "|--------------|--------------|------------|-------------|-------------|----------|---------------------|---------------------|-------|\n",
1469            ]
1470
1471            for item in iList:
1472                info.append("| {:<12} | {:<12} | {:<10} | {:>11} | {:>11} | {:>7}% | {:>19} | {:>19} | {:<5} |\n".format(
1473                    item["ticker"],
1474                    item["figi"],
1475                    item["type"],
1476                    "{:.2f}".format(float(item["currentPrice"]["closePrice"])),
1477                    "{:.2f}".format(float(item["currentPrice"]["lastPrice"])),
1478                    "{}{:.2f}".format("+" if item["currentPrice"]["changes"] > 0 else "", float(item["currentPrice"]["changes"])),
1479                    "{} / {}".format(
1480                        item["currentPrice"]["limitDown"] if item["currentPrice"]["limitDown"] is not None else "N/A",
1481                        item["currentPrice"]["limitUp"] if item["currentPrice"]["limitUp"] is not None else "N/A",
1482                    ),
1483                    "{} / {}".format(
1484                        item["currentPrice"]["sell"][0]["price"] if item["currentPrice"]["sell"] else "N/A",
1485                        item["currentPrice"]["buy"][0]["price"] if item["currentPrice"]["buy"] else "N/A",
1486                    ),
1487                    item["currency"],
1488                ))
1489
1490            infoText = "".join(info)
1491
1492            if show and not onlyFiles:
1493                uLogger.info("Only instruments with unique FIGIs are shown:\n{}".format(infoText))
1494
1495            if self.pricesFile and (show or onlyFiles):
1496                with open(self.pricesFile, "w", encoding="UTF-8") as fH:
1497                    fH.write(infoText)
1498
1499                uLogger.info("Price list for all instruments saved to file: [{}]".format(os.path.abspath(self.pricesFile)))
1500
1501                if self.useHTMLReports:
1502                    htmlFilePath = self.pricesFile.replace(".md", ".html") if self.pricesFile.endswith(".md") else self.pricesFile + ".html"
1503                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
1504                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Current prices", commonCSS=COMMON_CSS, markdown=infoText))
1505
1506                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
1507
1508        return infoText
1509
1510    def RequestTradingStatus(self) -> dict:
1511        """
1512        Requesting trading status for the instrument defined by `figi` variable.
1513
1514        REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetTradingStatus
1515
1516        Documentation: https://tinkoff.github.io/investAPI/marketdata/#gettradingstatusrequest
1517
1518        :return: dictionary with trading status attributes. Response example:
1519                 `{"figi": "TCS00A103X66", "tradingStatus": "SECURITY_TRADING_STATUS_NOT_AVAILABLE_FOR_TRADING",
1520                  "limitOrderAvailableFlag": false, "marketOrderAvailableFlag": false, "apiTradeAvailableFlag": true}`
1521        """
1522        if self._figi is None or not self._figi:
1523            uLogger.error("Variable `figi` must be defined for using this method!")
1524            raise Exception("FIGI required")
1525
1526        uLogger.debug("Requesting current trading status, FIGI: [{}]. Wait, please...".format(self._figi))
1527
1528        self.body = str({"figi": self._figi, "instrumentId": self._figi})
1529        tradingStatusURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetTradingStatus"
1530        tradingStatus = self.SendAPIRequest(tradingStatusURL, reqType="POST")
1531
1532        if self.moreDebug:
1533            uLogger.debug("Records about current trading status successfully received")
1534
1535        return tradingStatus
1536
1537    def RequestPortfolio(self) -> dict:
1538        """
1539        Requesting actual user's portfolio for current `accountId`.
1540
1541        REST API for user portfolio: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPortfolio
1542
1543        Documentation: https://tinkoff.github.io/investAPI/operations/#portfoliorequest
1544
1545        :return: dictionary with user's portfolio.
1546        """
1547        if self.accountId is None or not self.accountId:
1548            uLogger.error("Variable `accountId` must be defined for using this method!")
1549            raise Exception("Account ID required")
1550
1551        uLogger.debug("Requesting current actual user's portfolio. Wait, please...")
1552
1553        self.body = str({"accountId": self.accountId})
1554        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetPortfolio"
1555        rawPortfolio = self.SendAPIRequest(portfolioURL, reqType="POST")
1556
1557        if self.moreDebug:
1558            uLogger.debug("Records about user's portfolio successfully received")
1559
1560        return rawPortfolio
1561
1562    def RequestPositions(self) -> dict:
1563        """
1564        Requesting open positions by currencies and instruments for current `accountId`.
1565
1566        REST API for open positions: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPositions
1567
1568        Documentation: https://tinkoff.github.io/investAPI/operations/#positionsrequest
1569
1570        :return: dictionary with open positions by instruments.
1571        """
1572        if self.accountId is None or not self.accountId:
1573            uLogger.error("Variable `accountId` must be defined for using this method!")
1574            raise Exception("Account ID required")
1575
1576        uLogger.debug("Requesting current open positions in currencies and instruments. Wait, please...")
1577
1578        self.body = str({"accountId": self.accountId})
1579        positionsURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetPositions"
1580        rawPositions = self.SendAPIRequest(positionsURL, reqType="POST")
1581
1582        if self.moreDebug:
1583            uLogger.debug("Records about current open positions successfully received")
1584
1585        return rawPositions
1586
1587    def RequestPendingOrders(self) -> list:
1588        """
1589        Requesting current actual pending limit orders for current `accountId`.
1590
1591        REST API for pending (market) orders: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_GetOrders
1592
1593        Documentation: https://tinkoff.github.io/investAPI/orders/#getordersrequest
1594
1595        :return: list of dictionaries with pending limit orders.
1596        """
1597        if self.accountId is None or not self.accountId:
1598            uLogger.error("Variable `accountId` must be defined for using this method!")
1599            raise Exception("Account ID required")
1600
1601        uLogger.debug("Requesting current actual pending limit orders. Wait, please...")
1602
1603        self.body = str({"accountId": self.accountId})
1604        ordersURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/GetOrders"
1605        rawResponse = self.SendAPIRequest(ordersURL, reqType="POST")
1606
1607        if "orders" in rawResponse.keys():
1608            rawOrders = rawResponse["orders"]
1609            uLogger.debug("[{}] records about pending limit orders received".format(len(rawOrders)))
1610
1611        else:
1612            rawOrders = []
1613            uLogger.debug("No pending limit orders returned! rawResponse = {}".format(rawResponse))
1614
1615        return rawOrders
1616
1617    def RequestStopOrders(self) -> list:
1618        """
1619        Requesting current actual stop orders for current `accountId`.
1620
1621        REST API for opened stop-orders: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_GetStopOrders
1622
1623        Documentation: https://tinkoff.github.io/investAPI/stoporders/#getstopordersrequest
1624
1625        :return: list of dictionaries with stop orders.
1626        """
1627        if self.accountId is None or not self.accountId:
1628            uLogger.error("Variable `accountId` must be defined for using this method!")
1629            raise Exception("Account ID required")
1630
1631        uLogger.debug("Requesting current actual stop orders. Wait, please...")
1632
1633        self.body = str({"accountId": self.accountId})
1634        stopOrdersURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/GetStopOrders"
1635        rawResponse = self.SendAPIRequest(stopOrdersURL, reqType="POST")
1636
1637        if "stopOrders" in rawResponse.keys():
1638            rawStopOrders = rawResponse["stopOrders"]
1639            uLogger.debug("[{}] records about stop orders received".format(len(rawStopOrders)))
1640
1641        else:
1642            rawStopOrders = []
1643            uLogger.debug("No stop orders returned! rawResponse = {}".format(rawResponse))
1644
1645        return rawStopOrders
1646
1647    def Overview(self, show: bool = False, details: str = "full", onlyFiles=False) -> dict:
1648        """
1649        Get portfolio: all open positions, orders and some statistics for current `accountId`.
1650        If `overviewFile`, `overviewDigestFile`, `overviewPositionsFile`, `overviewOrdersFile`, `overviewAnalyticsFile`
1651        and `overviewBondsCalendarFile` are defined then also save information to file.
1652
1653        WARNING! It is not recommended to run this method too many times in a loop! The server receives
1654        many requests about the state of the portfolio, and then, based on the received data, a large number
1655        of calculation and statistics are collected.
1656
1657        :param show: if `False` then only dictionary returns, if `True` then show more debug information.
1658        :param details: how detailed should the information be?
1659        - `full` — shows full available information about portfolio status (by default),
1660        - `positions` — shows only open positions,
1661        - `orders` — shows only sections of open limits and stop orders.
1662        - `digest` — show a short digest of the portfolio status,
1663        - `analytics` — shows only the analytics section and the distribution of the portfolio by various categories,
1664        - `calendar` — shows only the bonds calendar section (if these present in portfolio).
1665        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
1666        :return: dictionary with client's raw portfolio and some statistics.
1667        """
1668        if self.accountId is None or not self.accountId:
1669            uLogger.error("Variable `accountId` must be defined for using this method!")
1670            raise Exception("Account ID required")
1671
1672        view = {
1673            "raw": {  # --- raw portfolio responses from broker with user portfolio data:
1674                "headers": {},  # list of dictionaries, response headers without "positions" section
1675                "Currencies": [],  # list of dictionaries, open trades with currencies from "positions" section
1676                "Shares": [],  # list of dictionaries, open trades with shares from "positions" section
1677                "Bonds": [],  # list of dictionaries, open trades with bonds from "positions" section
1678                "Etfs": [],  # list of dictionaries, open trades with etfs from "positions" section
1679                "Futures": [],  # list of dictionaries, open trades with futures from "positions" section
1680                "positions": {},  # raw response from broker: dictionary with current available or blocked currencies and instruments for client
1681                "orders": [],  # raw response from broker: list of dictionaries with all pending (market) orders
1682                "stopOrders": [],  # raw response from broker: list of dictionaries with all stop orders
1683                "currenciesCurrentPrices": {"rub": {"name": "Российский рубль", "currentPrice": 1.}},  # dict with prices of all currencies in RUB
1684            },
1685            "stat": {  # --- some statistics calculated using "raw" sections:
1686                "portfolioCostRUB": 0.,  # portfolio cost in RUB (Russian Rouble)
1687                "availableRUB": 0.,  # available rubles (without other currencies)
1688                "blockedRUB": 0.,  # blocked sum in Russian Rouble
1689                "totalChangesRUB": 0.,  # changes for all open trades in RUB
1690                "totalChangesPercentRUB": 0.,  # changes for all open trades in percents
1691                "allCurrenciesCostRUB": 0.,  # costs of all currencies (include rubles) in RUB
1692                "sharesCostRUB": 0.,  # costs of all shares in RUB
1693                "bondsCostRUB": 0.,  # costs of all bonds in RUB
1694                "etfsCostRUB": 0.,  # costs of all etfs in RUB
1695                "futuresCostRUB": 0.,  # costs of all futures in RUB
1696                "Currencies": [],  # list of dictionaries of all currencies statistics
1697                "Shares": [],  # list of dictionaries of all shares statistics
1698                "Bonds": [],  # list of dictionaries of all bonds statistics
1699                "Etfs": [],  # list of dictionaries of all etfs statistics
1700                "Futures": [],  # list of dictionaries of all futures statistics
1701                "orders": [],  # list of dictionaries of all pending (market) orders and it's parameters
1702                "stopOrders": [],  # list of dictionaries of all stop orders and it's parameters
1703                "blockedCurrencies": {},  # dict with blocked instruments and currencies, e.g. {"rub": 1291.87, "usd": 6.21}
1704                "blockedInstruments": {},  # dict with blocked  by FIGI, e.g. {}
1705                "funds": {},  # dict with free funds for trading (total - blocked), by all currencies, e.g. {"rub": {"total": 10000.99, "totalCostRUB": 10000.99, "free": 1234.56, "freeCostRUB": 1234.56}, "usd": {"total": 250.55, "totalCostRUB": 15375.80, "free": 125.05, "freeCostRUB": 7687.50}}
1706            },
1707            "analytics": {  # --- some analytics of portfolio:
1708                "distrByAssets": {},  # portfolio distribution by assets
1709                "distrByCompanies": {},  # portfolio distribution by companies
1710                "distrBySectors": {},  # portfolio distribution by sectors
1711                "distrByCurrencies": {},  # portfolio distribution by currencies
1712                "distrByCountries": {},  # portfolio distribution by countries
1713                "bondsCalendar": None,  # bonds payment calendar as Pandas DataFrame (if these present in portfolio)
1714            }
1715        }
1716
1717        details = details.lower()
1718        availableDetails = ["full", "positions", "orders", "analytics", "calendar", "digest"]
1719        if details not in availableDetails:
1720            details = "full"
1721            uLogger.debug("Requested incorrect details! The `details` must be one of this strings: {}. Details parameter set to `full` be default.".format(availableDetails))
1722
1723        uLogger.debug("Requesting portfolio of a client. Wait, please...")
1724
1725        portfolioResponse = self.RequestPortfolio()  # current user's portfolio (dict)
1726        view["raw"]["positions"] = self.RequestPositions()  # current open positions by instruments (dict)
1727        view["raw"]["orders"] = self.RequestPendingOrders()  # current actual pending limit orders (list)
1728        view["raw"]["stopOrders"] = self.RequestStopOrders()  # current actual stop orders (list)
1729
1730        # save response headers without "positions" section:
1731        for key in portfolioResponse.keys():
1732            if key != "positions":
1733                view["raw"]["headers"][key] = portfolioResponse[key]
1734
1735            else:
1736                continue
1737
1738        # Re-sorting and separating given raw instruments and currencies by type: https://tinkoff.github.io/investAPI/operations/#operation
1739        # Type of instrument must be only one of supported types in TKS_INSTRUMENTS
1740        for item in portfolioResponse["positions"]:
1741            if item["instrumentType"] == "currency":
1742                self._figi = item["figi"]
1743                if not self._figi and item["ticker"]:
1744                    self._ticker = item["ticker"]
1745                    self._figi = self.SearchByTicker()["figi"]  # Get FIGI to avoid warnings
1746
1747                curr = self.SearchByFIGI(requestPrice=False)
1748
1749                # current price of currency in RUB:
1750                view["raw"]["currenciesCurrentPrices"][curr["nominal"]["currency"]] = {
1751                    "name": curr["name"],
1752                    "currentPrice": NanoToFloat(
1753                        item["currentPrice"]["units"],
1754                        item["currentPrice"]["nano"]
1755                    ),
1756                }
1757
1758                view["raw"]["Currencies"].append(item)
1759
1760            elif item["instrumentType"] == "share":
1761                view["raw"]["Shares"].append(item)
1762
1763            elif item["instrumentType"] == "bond":
1764                view["raw"]["Bonds"].append(item)
1765
1766            elif item["instrumentType"] == "etf":
1767                view["raw"]["Etfs"].append(item)
1768
1769            elif item["instrumentType"] == "futures":
1770                view["raw"]["Futures"].append(item)
1771
1772            else:
1773                continue
1774
1775        # how many volume of currencies (by ISO currency name) are blocked:
1776        for item in view["raw"]["positions"]["blocked"]:
1777            blocked = NanoToFloat(item["units"], item["nano"])
1778            if blocked > 0:
1779                view["stat"]["blockedCurrencies"][item["currency"]] = blocked
1780
1781        # how many volume of instruments (by FIGI) are blocked:
1782        for item in view["raw"]["positions"]["securities"]:
1783            blocked = int(item["blocked"])
1784            if blocked > 0:
1785                view["stat"]["blockedInstruments"][item["figi"]] = blocked
1786
1787        allBlocked = {**view["stat"]["blockedCurrencies"], **view["stat"]["blockedInstruments"]}
1788
1789        if "rub" in allBlocked.keys():
1790            view["stat"]["blockedRUB"] = allBlocked["rub"]  # blocked rubles
1791
1792        # --- saving current total amount in RUB of all currencies (with ruble), shares, bonds, etfs, futures and currencies:
1793        view["stat"]["allCurrenciesCostRUB"] = NanoToFloat(portfolioResponse["totalAmountCurrencies"]["units"], portfolioResponse["totalAmountCurrencies"]["nano"])
1794        view["stat"]["sharesCostRUB"] = NanoToFloat(portfolioResponse["totalAmountShares"]["units"], portfolioResponse["totalAmountShares"]["nano"])
1795        view["stat"]["bondsCostRUB"] = NanoToFloat(portfolioResponse["totalAmountBonds"]["units"], portfolioResponse["totalAmountBonds"]["nano"])
1796        view["stat"]["etfsCostRUB"] = NanoToFloat(portfolioResponse["totalAmountEtf"]["units"], portfolioResponse["totalAmountEtf"]["nano"])
1797        view["stat"]["futuresCostRUB"] = NanoToFloat(portfolioResponse["totalAmountFutures"]["units"], portfolioResponse["totalAmountFutures"]["nano"])
1798        view["stat"]["portfolioCostRUB"] = sum([
1799            view["stat"]["allCurrenciesCostRUB"],
1800            view["stat"]["sharesCostRUB"],
1801            view["stat"]["bondsCostRUB"],
1802            view["stat"]["etfsCostRUB"],
1803            view["stat"]["futuresCostRUB"],
1804        ])
1805
1806        # --- calculating some portfolio statistics:
1807        byComp = {}  # distribution by companies
1808        bySect = {}  # distribution by sectors
1809        byCurr = {}  # distribution by currencies (include RUB)
1810        unknownCountryName = "All other countries"  # default name for instruments without "countryOfRisk" and "countryOfRiskName"
1811        byCountry = {unknownCountryName: {"cost": 0, "percent": 0.}}  # distribution by countries (currencies are included in their countries)
1812
1813        for item in portfolioResponse["positions"]:
1814            self._figi = item["figi"]
1815            if not self._figi and item["ticker"]:
1816                self._ticker = item["ticker"]
1817                self._figi = self.SearchByTicker()["figi"]  # Get FIGI to avoid warnings
1818
1819            instrument = self.SearchByFIGI(requestPrice=False)  # full raw info about instrument by FIGI
1820
1821            if instrument:
1822                if item["instrumentType"] == "currency" and instrument["nominal"]["currency"] in allBlocked.keys():
1823                    blocked = allBlocked[instrument["nominal"]["currency"]]  # blocked volume of currency
1824
1825                elif item["instrumentType"] != "currency" and item["figi"] in allBlocked.keys():
1826                    blocked = allBlocked[item["figi"]]  # blocked volume of other instruments
1827
1828                else:
1829                    blocked = 0
1830
1831                volume = NanoToFloat(item["quantity"]["units"], item["quantity"]["nano"])  # available volume of instrument
1832                lots = NanoToFloat(item["quantityLots"]["units"], item["quantityLots"]["nano"])  # available volume in lots of instrument
1833                direction = "Long" if lots >= 0 else "Short"  # direction of an instrument's position: short or long
1834                curPrice = NanoToFloat(item["currentPrice"]["units"], item["currentPrice"]["nano"])  # current instrument's price
1835                average = NanoToFloat(item["averagePositionPriceFifo"]["units"], item["averagePositionPriceFifo"]["nano"])  # current average position price
1836                profit = NanoToFloat(item["expectedYield"]["units"], item["expectedYield"]["nano"])  # expected profit at current moment
1837                currency = instrument["currency"] if (item["instrumentType"] == "share" or item["instrumentType"] == "etf" or item["instrumentType"] == "future") else instrument["nominal"]["currency"]  # currency name rub, usd, eur etc.
1838                cost = curPrice if "currentNkd" not in item.keys() else (curPrice + NanoToFloat(item["currentNkd"]["units"], item["currentNkd"]["nano"])) * volume  # current cost of all volume of instrument in basic asset
1839                baseCurrencyName = item["currentPrice"]["currency"]  # name of base currency (rub)
1840                countryName = "[{}] {}".format(instrument["countryOfRisk"], instrument["countryOfRiskName"]) if "countryOfRisk" in instrument.keys() and "countryOfRiskName" in instrument.keys() and instrument["countryOfRisk"] and instrument["countryOfRiskName"] else unknownCountryName
1841                costRUB = cost if item["instrumentType"] == "currency" else cost * view["raw"]["currenciesCurrentPrices"][currency]["currentPrice"]  # cost in rubles
1842                percentCostRUB = 100 * costRUB / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.  # instrument's part in percent of full portfolio cost
1843
1844                statData = {
1845                    "figi": item["figi"],  # FIGI from REST API "GetPortfolio" method
1846                    "ticker": instrument["ticker"],  # ticker by FIGI
1847                    "currency": currency,  # currency name rub, usd, eur etc. for instrument price
1848                    "volume": volume,  # available volume of instrument
1849                    "lots": lots,  # volume in lots of instrument
1850                    "direction": direction,  # direction of an instrument's position: short or long
1851                    "blocked": blocked,  # blocked volume of currency or instrument
1852                    "currentPrice": curPrice,  # current instrument's price in basic asset
1853                    "average": average,  # current average position price
1854                    "cost": cost,  # current cost of all volume of instrument in basic asset
1855                    "baseCurrencyName": baseCurrencyName,  # name of base currency (rub)
1856                    "costRUB": costRUB,  # cost of instrument in ruble
1857                    "percentCostRUB": percentCostRUB,  # instrument's part in percent of full portfolio cost in RUB
1858                    "profit": profit,  # expected profit at current moment
1859                    "percentProfit": 100 * profit / (average * volume) if average != 0 and volume != 0 else 0,  # expected percents of profit at current moment for this instrument
1860                    "sector": instrument["sector"] if "sector" in instrument.keys() and instrument["sector"] else "other",
1861                    "name": instrument["name"] if "name" in instrument.keys() else "",  # human-readable names of instruments
1862                    "isoCurrencyName": instrument["isoCurrencyName"] if "isoCurrencyName" in instrument.keys() else "",  # ISO name for currencies only
1863                    "country": countryName,  # e.g. "[RU] Российская Федерация" or unknownCountryName
1864                    "step": instrument["step"],  # minimum price increment
1865                }
1866
1867                # adding distribution by unique countries:
1868                if statData["country"] not in byCountry.keys():
1869                    byCountry[statData["country"]] = {"cost": costRUB, "percent": percentCostRUB}
1870
1871                else:
1872                    byCountry[statData["country"]]["cost"] += costRUB
1873                    byCountry[statData["country"]]["percent"] += percentCostRUB
1874
1875                if item["instrumentType"] != "currency":
1876                    # adding distribution by unique companies:
1877                    if statData["name"]:
1878                        if statData["name"] not in byComp.keys():
1879                            byComp[statData["name"]] = {"ticker": statData["ticker"], "cost": costRUB, "percent": percentCostRUB}
1880
1881                        else:
1882                            byComp[statData["name"]]["cost"] += costRUB
1883                            byComp[statData["name"]]["percent"] += percentCostRUB
1884
1885                    # adding distribution by unique sectors:
1886                    if statData["sector"] not in bySect.keys():
1887                        bySect[statData["sector"]] = {"cost": costRUB, "percent": percentCostRUB}
1888
1889                    else:
1890                        bySect[statData["sector"]]["cost"] += costRUB
1891                        bySect[statData["sector"]]["percent"] += percentCostRUB
1892
1893                # adding distribution by unique currencies:
1894                if currency not in byCurr.keys():
1895                    byCurr[currency] = {
1896                        "name": view["raw"]["currenciesCurrentPrices"][currency]["name"],
1897                        "cost": costRUB,
1898                        "percent": percentCostRUB
1899                    }
1900
1901                else:
1902                    byCurr[currency]["cost"] += costRUB
1903                    byCurr[currency]["percent"] += percentCostRUB
1904
1905                # saving statistics for every instrument:
1906                if item["instrumentType"] == "currency":
1907                    view["stat"]["Currencies"].append(statData)
1908
1909                    # update dict with free funds for trading (total - blocked) by currencies
1910                    # e.g. {"rub": {"total": 10000.99, "totalCostRUB": 10000.99, "free": 1234.56, "freeCostRUB": 1234.56}, "usd": {"total": 250.55, "totalCostRUB": 15375.80, "free": 125.05, "freeCostRUB": 7687.50}}
1911                    view["stat"]["funds"][currency] = {
1912                        "total": volume,
1913                        "totalCostRUB": costRUB,  # total volume cost in rubles
1914                        "free": volume - blocked,
1915                        "freeCostRUB": costRUB * ((volume - blocked) / volume) if volume > 0 else 0,  # free volume cost in rubles
1916                    }
1917
1918                elif item["instrumentType"] == "share":
1919                    view["stat"]["Shares"].append(statData)
1920
1921                elif item["instrumentType"] == "bond":
1922                    view["stat"]["Bonds"].append(statData)
1923
1924                elif item["instrumentType"] == "etf":
1925                    view["stat"]["Etfs"].append(statData)
1926
1927                elif item["instrumentType"] == "Futures":
1928                    view["stat"]["Futures"].append(statData)
1929
1930                else:
1931                    continue
1932
1933        # total changes in Russian Ruble:
1934        view["stat"]["availableRUB"] = view["stat"]["allCurrenciesCostRUB"] - sum([item["cost"] for item in view["stat"]["Currencies"]])  # available RUB without other currencies
1935        view["stat"]["totalChangesPercentRUB"] = NanoToFloat(view["raw"]["headers"]["expectedYield"]["units"], view["raw"]["headers"]["expectedYield"]["nano"]) if "expectedYield" in view["raw"]["headers"].keys() else 0.
1936        startCost = view["stat"]["portfolioCostRUB"] / (1 + view["stat"]["totalChangesPercentRUB"] / 100)
1937        view["stat"]["totalChangesRUB"] = view["stat"]["portfolioCostRUB"] - startCost
1938        view["stat"]["funds"]["rub"] = {
1939            "total": view["stat"]["availableRUB"],
1940            "totalCostRUB": view["stat"]["availableRUB"],
1941            "free": view["stat"]["availableRUB"] - view["stat"]["blockedRUB"],
1942            "freeCostRUB": view["stat"]["availableRUB"] - view["stat"]["blockedRUB"],
1943        }
1944
1945        # --- pending limit orders sector data:
1946        uniquePendingOrdersFIGIs = []  # unique FIGIs of pending limit orders to avoid many times price requests
1947        uniquePendingOrders = {}  # unique instruments with FIGIs as dictionary keys
1948
1949        for item in view["raw"]["orders"]:
1950            self._figi = item["figi"]
1951
1952            if item["figi"] not in uniquePendingOrdersFIGIs:
1953                instrument = self.SearchByFIGI(requestPrice=True)  # full raw info about instrument by FIGI, price requests only one time
1954
1955                uniquePendingOrdersFIGIs.append(item["figi"])
1956                uniquePendingOrders[item["figi"]] = instrument
1957
1958            else:
1959                instrument = uniquePendingOrders[item["figi"]]
1960
1961            if instrument:
1962                action = TKS_ORDER_DIRECTIONS[item["direction"]]
1963                orderType = TKS_ORDER_TYPES[item["orderType"]]
1964                orderState = TKS_ORDER_STATES[item["executionReportStatus"]]
1965                orderDate = item["orderDate"].replace("T", " ").replace("Z", "").split(".")[0]  # date in UTC format, e.g. "2022-12-31T23:59:59.123456Z"
1966
1967                # current instrument's price (last sellers order if buy, and last buyers order if sell):
1968                if item["direction"] == "ORDER_DIRECTION_BUY":
1969                    lastPrice = instrument["currentPrice"]["sell"][0]["price"] if instrument["currentPrice"]["sell"] else "N/A"
1970
1971                else:
1972                    lastPrice = instrument["currentPrice"]["buy"][0]["price"] if instrument["currentPrice"]["buy"] else "N/A"
1973
1974                # requested price for order execution:
1975                target = NanoToFloat(item["initialSecurityPrice"]["units"], item["initialSecurityPrice"]["nano"])
1976
1977                # necessary changes in percent to reach target from current price:
1978                changes = 100 * (lastPrice - target) / target if lastPrice != "N/A" and target > 0 else 0
1979
1980                view["stat"]["orders"].append({
1981                    "orderID": item["orderId"],  # orderId number parameter of current order
1982                    "figi": item["figi"],  # FIGI identification
1983                    "ticker": instrument["ticker"],  # ticker name by FIGI
1984                    "lotsRequested": item["lotsRequested"],  # requested lots value
1985                    "lotsExecuted": item["lotsExecuted"],  # how many lots are executed
1986                    "currentPrice": lastPrice,  # current instrument's price for defined action
1987                    "targetPrice": target,  # requested price for order execution in base currency
1988                    "baseCurrencyName": item["initialSecurityPrice"]["currency"],  # name of base currency
1989                    "percentChanges": changes,  # changes in percent to target from current price
1990                    "currency": item["currency"],  # instrument's currency name
1991                    "action": action,  # sell / buy / Unknown from TKS_ORDER_DIRECTIONS
1992                    "type": orderType,  # type of order from TKS_ORDER_TYPES
1993                    "status": orderState,  # order status from TKS_ORDER_STATES
1994                    "date": orderDate,  # string with order date and time from UTC format (without nano seconds part)
1995                })
1996
1997        # --- stop orders sector data:
1998        uniqueStopOrdersFIGIs = []  # unique FIGIs of stop orders to avoid many times price requests
1999        uniqueStopOrders = {}  # unique instruments with FIGIs as dictionary keys
2000
2001        for item in view["raw"]["stopOrders"]:
2002            self._figi = item["figi"]
2003
2004            if item["figi"] not in uniqueStopOrdersFIGIs:
2005                instrument = self.SearchByFIGI(requestPrice=True)  # full raw info about instrument by FIGI, price requests only one time
2006
2007                uniqueStopOrdersFIGIs.append(item["figi"])
2008                uniqueStopOrders[item["figi"]] = instrument
2009
2010            else:
2011                instrument = uniqueStopOrders[item["figi"]]
2012
2013            if instrument:
2014                action = TKS_STOP_ORDER_DIRECTIONS[item["direction"]]
2015                orderType = TKS_STOP_ORDER_TYPES[item["orderType"]]
2016                createDate = item["createDate"].replace("T", " ").replace("Z", "").split(".")[0]  # date in UTC format, e.g. "2022-12-31T23:59:59.123456Z"
2017
2018                # hack: server response can't contain "expirationTime" key if it is not "Until date" type of stop order
2019                if "expirationTime" in item.keys():
2020                    expType = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_DATE"]
2021                    expDate = item["expirationTime"].replace("T", " ").replace("Z", "").split(".")[0]
2022
2023                else:
2024                    expType = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_CANCEL"]
2025                    expDate = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_UNSPECIFIED"]
2026
2027                # current instrument's price (last sellers order if buy, and last buyers order if sell):
2028                if item["direction"] == "STOP_ORDER_DIRECTION_BUY":
2029                    lastPrice = instrument["currentPrice"]["sell"][0]["price"] if instrument["currentPrice"]["sell"] else "N/A"
2030
2031                else:
2032                    lastPrice = instrument["currentPrice"]["buy"][0]["price"] if instrument["currentPrice"]["buy"] else "N/A"
2033
2034                # requested price when stop-order executed:
2035                target = NanoToFloat(item["stopPrice"]["units"], item["stopPrice"]["nano"])
2036
2037                # price for limit-order, set up when stop-order executed:
2038                limit = NanoToFloat(item["price"]["units"], item["price"]["nano"])
2039
2040                # necessary changes in percent to reach target from current price:
2041                changes = 100 * (lastPrice - target) / target if lastPrice != "N/A" and target > 0 else 0
2042
2043                view["stat"]["stopOrders"].append({
2044                    "orderID": item["stopOrderId"],  # stopOrderId number parameter of current stop-order
2045                    "figi": item["figi"],  # FIGI identification
2046                    "ticker": instrument["ticker"],  # ticker name by FIGI
2047                    "lotsRequested": item["lotsRequested"],  # requested lots value
2048                    "currentPrice": lastPrice,  # current instrument's price for defined action
2049                    "targetPrice": target,  # requested price for stop-order execution in base currency
2050                    "limitPrice": limit,  # price for limit-order, set up when stop-order executed, 0 if market order
2051                    "baseCurrencyName": item["stopPrice"]["currency"],  # name of base currency
2052                    "percentChanges": changes,  # changes in percent to target from current price
2053                    "currency": item["currency"],  # instrument's currency name
2054                    "action": action,  # sell / buy / Unknown from TKS_STOP_ORDER_DIRECTIONS
2055                    "type": orderType,  # type of order from TKS_STOP_ORDER_TYPES
2056                    "expType": expType,  # expiration type of stop-order from TKS_STOP_ORDER_EXPIRATION_TYPES
2057                    "createDate": createDate,  # string with created order date and time from UTC format (without nano seconds part)
2058                    "expDate": expDate,  # string with expiration order date and time from UTC format (without nano seconds part)
2059                })
2060
2061        # --- calculating data for analytics section:
2062        # portfolio distribution by assets:
2063        view["analytics"]["distrByAssets"] = {
2064            "Ruble": {
2065                "uniques": 1,
2066                "cost": view["stat"]["availableRUB"],
2067                "percent": 100 * view["stat"]["availableRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2068            },
2069            "Currencies": {
2070                "uniques": len(view["stat"]["Currencies"]),  # all foreign currencies without RUB
2071                "cost": view["stat"]["allCurrenciesCostRUB"] - view["stat"]["availableRUB"],
2072                "percent": 100 * (view["stat"]["allCurrenciesCostRUB"] - view["stat"]["availableRUB"]) / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2073            },
2074            "Shares": {
2075                "uniques": len(view["stat"]["Shares"]),
2076                "cost": view["stat"]["sharesCostRUB"],
2077                "percent": 100 * view["stat"]["sharesCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2078            },
2079            "Bonds": {
2080                "uniques": len(view["stat"]["Bonds"]),
2081                "cost": view["stat"]["bondsCostRUB"],
2082                "percent": 100 * view["stat"]["bondsCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2083            },
2084            "Etfs": {
2085                "uniques": len(view["stat"]["Etfs"]),
2086                "cost": view["stat"]["etfsCostRUB"],
2087                "percent": 100 * view["stat"]["etfsCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2088            },
2089            "Futures": {
2090                "uniques": len(view["stat"]["Futures"]),
2091                "cost": view["stat"]["futuresCostRUB"],
2092                "percent": 100 * view["stat"]["futuresCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2093            },
2094        }
2095
2096        # portfolio distribution by companies:
2097        view["analytics"]["distrByCompanies"]["All money cash"] = {
2098            "ticker": "",
2099            "cost": view["stat"]["allCurrenciesCostRUB"],
2100            "percent": 100 * view["stat"]["allCurrenciesCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2101        }
2102        view["analytics"]["distrByCompanies"].update(byComp)
2103
2104        # portfolio distribution by sectors:
2105        view["analytics"]["distrBySectors"]["All money cash"] = {
2106            "cost": view["analytics"]["distrByCompanies"]["All money cash"]["cost"],
2107            "percent": view["analytics"]["distrByCompanies"]["All money cash"]["percent"],
2108        }
2109        view["analytics"]["distrBySectors"].update(bySect)
2110
2111        # portfolio distribution by currencies:
2112        if "rub" not in view["analytics"]["distrByCurrencies"].keys():
2113            view["analytics"]["distrByCurrencies"]["rub"] = {"name": "Российский рубль", "cost": 0, "percent": 0}
2114
2115            if self.moreDebug:
2116                uLogger.debug("Fast hack to avoid issues #71 in `Portfolio distribution by currencies` section. Server not returned current available rubles!")
2117
2118        view["analytics"]["distrByCurrencies"].update(byCurr)
2119        view["analytics"]["distrByCurrencies"]["rub"]["cost"] += view["analytics"]["distrByAssets"]["Ruble"]["cost"]
2120        view["analytics"]["distrByCurrencies"]["rub"]["percent"] += view["analytics"]["distrByAssets"]["Ruble"]["percent"]
2121
2122        # portfolio distribution by countries:
2123        if "[RU] Российская Федерация" not in view["analytics"]["distrByCountries"].keys():
2124            view["analytics"]["distrByCountries"]["[RU] Российская Федерация"] = {"cost": 0, "percent": 0}
2125
2126            if self.moreDebug:
2127                uLogger.debug("Fast hack to avoid issues #71 in `Portfolio distribution by countries` section. Server not returned current available rubles!")
2128
2129        view["analytics"]["distrByCountries"].update(byCountry)
2130        view["analytics"]["distrByCountries"]["[RU] Российская Федерация"]["cost"] += view["analytics"]["distrByAssets"]["Ruble"]["cost"]
2131        view["analytics"]["distrByCountries"]["[RU] Российская Федерация"]["percent"] += view["analytics"]["distrByAssets"]["Ruble"]["percent"]
2132
2133        # --- Prepare text statistics overview in human-readable:
2134        if show or onlyFiles:
2135            actualOnDate = datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)
2136
2137            # Whatever the value `details`, header not changes:
2138            info = [
2139                "# Client's portfolio\n\n",
2140                "* **Actual on date:** [{} UTC]\n".format(actualOnDate),
2141                "* **Account ID:** [{}]\n".format(self.accountId),
2142            ]
2143
2144            if details in ["full", "positions", "digest"]:
2145                info.extend([
2146                    "* **Portfolio cost:** {:.2f} RUB\n".format(view["stat"]["portfolioCostRUB"]),
2147                    "* **Changes:** {}{:.2f} RUB ({}{:.2f}%)\n\n".format(
2148                        "+" if view["stat"]["totalChangesRUB"] > 0 else "",
2149                        view["stat"]["totalChangesRUB"],
2150                        "+" if view["stat"]["totalChangesPercentRUB"] > 0 else "",
2151                        view["stat"]["totalChangesPercentRUB"],
2152                    ),
2153                ])
2154
2155            if details in ["full", "positions"]:
2156                info.extend([
2157                    "## Open positions\n\n",
2158                    "| Ticker [FIGI]               | Volume (blocked)                | Lots     | Curr. price  | Avg. price   | Current volume cost | Profit (%)                   |\n",
2159                    "|-----------------------------|---------------------------------|----------|--------------|--------------|---------------------|------------------------------|\n",
2160                    "| **Ruble:**                  | {:>31} |          |              |              |                     |                              |\n".format(
2161                        "{:.2f} ({:.2f}) rub".format(
2162                            view["stat"]["availableRUB"],
2163                            view["stat"]["blockedRUB"],
2164                        )
2165                    )
2166                ])
2167
2168                def _SplitStr(CostRUB: float = 0, typeStr: str = "", noTradeStr: str = "") -> list:
2169                    return [
2170                        "|                             |                                 |          |              |              |                     |                              |\n",
2171                        "| {:<27} |                                 |          |              |              | {:>19} |                              |\n".format(
2172                            noTradeStr if noTradeStr else typeStr,
2173                            "" if noTradeStr else "{:.2f} RUB".format(CostRUB),
2174                        ),
2175                    ]
2176
2177                def _InfoStr(data: dict, isCurr: bool = False) -> str:
2178                    return "| {:<27} | {:>31} | {:<8} | {:>12} | {:>12} | {:>19} | {:<28} |\n".format(
2179                        "{} [{}]".format(data["ticker"], data["figi"]),
2180                        "{:.2f} ({:.2f}) {}".format(
2181                            data["volume"],
2182                            data["blocked"],
2183                            data["currency"],
2184                        ) if isCurr else "{:.0f} ({:.0f})".format(
2185                            data["volume"],
2186                            data["blocked"],
2187                        ),
2188                        "—" if isCurr else "{:.4f}".format(data["lots"]).rstrip("0").rstrip("."),
2189                        "{:.2f} {}".format(data["currentPrice"], data["baseCurrencyName"]) if data["currentPrice"] > 0 else "n/a",
2190                        "{:.2f} {}".format(data["average"], data["baseCurrencyName"]) if data["average"] > 0 else "n/a",
2191                        "{:.2f} {}".format(data["cost"], data["baseCurrencyName"]),
2192                        "{}{:.2f} {} ({}{:.2f}%)".format(
2193                            "+" if data["profit"] > 0 else "",
2194                            data["profit"], data["baseCurrencyName"],
2195                            "+" if data["percentProfit"] > 0 else "",
2196                            data["percentProfit"],
2197                        ),
2198                    )
2199
2200                # --- Show currencies section:
2201                if view["stat"]["Currencies"]:
2202                    info.extend(_SplitStr(CostRUB=view["analytics"]["distrByAssets"]["Currencies"]["cost"], typeStr="**Currencies:**"))
2203                    for item in view["stat"]["Currencies"]:
2204                        info.append(_InfoStr(item, isCurr=True))
2205
2206                else:
2207                    info.extend(_SplitStr(noTradeStr="**Currencies:** no trades"))
2208
2209                # --- Show shares section:
2210                if view["stat"]["Shares"]:
2211                    info.extend(_SplitStr(CostRUB=view["stat"]["sharesCostRUB"], typeStr="**Shares:**"))
2212
2213                    for item in view["stat"]["Shares"]:
2214                        info.append(_InfoStr(item))
2215
2216                else:
2217                    info.extend(_SplitStr(noTradeStr="**Shares:** no trades"))
2218
2219                # --- Show bonds section:
2220                if view["stat"]["Bonds"]:
2221                    info.extend(_SplitStr(CostRUB=view["stat"]["bondsCostRUB"], typeStr="**Bonds:**"))
2222
2223                    for item in view["stat"]["Bonds"]:
2224                        info.append(_InfoStr(item))
2225
2226                else:
2227                    info.extend(_SplitStr(noTradeStr="**Bonds:** no trades"))
2228
2229                # --- Show etfs section:
2230                if view["stat"]["Etfs"]:
2231                    info.extend(_SplitStr(CostRUB=view["stat"]["etfsCostRUB"], typeStr="**Etfs:**"))
2232
2233                    for item in view["stat"]["Etfs"]:
2234                        info.append(_InfoStr(item))
2235
2236                else:
2237                    info.extend(_SplitStr(noTradeStr="**Etfs:** no trades"))
2238
2239                # --- Show futures section:
2240                if view["stat"]["Futures"]:
2241                    info.extend(_SplitStr(CostRUB=view["stat"]["futuresCostRUB"], typeStr="**Futures:**"))
2242
2243                    for item in view["stat"]["Futures"]:
2244                        info.append(_InfoStr(item))
2245
2246                else:
2247                    info.extend(_SplitStr(noTradeStr="**Futures:** no trades"))
2248
2249            if details in ["full", "orders"]:
2250                # --- Show pending limit orders section:
2251                if view["stat"]["orders"]:
2252                    info.extend([
2253                        "\n## Opened pending limit-orders: [{}]\n".format(len(view["stat"]["orders"])),
2254                        "\n| Ticker [FIGI]               | Order ID       | Lots (exec.) | Current price (% delta) | Target price  | Action    | Type      | Create date (UTC)       |\n",
2255                        "|-----------------------------|----------------|--------------|-------------------------|---------------|-----------|-----------|-------------------------|\n",
2256                    ])
2257
2258                    for item in view["stat"]["orders"]:
2259                        info.append("| {:<27} | {:<14} | {:<12} | {:>23} | {:>13} | {:<9} | {:<9} | {:<23} |\n".format(
2260                            "{} [{}]".format(item["ticker"], item["figi"]),
2261                            item["orderID"],
2262                            "{} ({})".format(item["lotsRequested"], item["lotsExecuted"]),
2263                            "{} {} ({}{:.2f}%)".format(
2264                                "{}".format(item["currentPrice"]) if isinstance(item["currentPrice"], str) else "{:.2f}".format(float(item["currentPrice"])),
2265                                item["baseCurrencyName"],
2266                                "+" if item["percentChanges"] > 0 else "",
2267                                float(item["percentChanges"]),
2268                            ),
2269                            "{:.2f} {}".format(float(item["targetPrice"]), item["baseCurrencyName"]),
2270                            item["action"],
2271                            item["type"],
2272                            item["date"],
2273                        ))
2274
2275                else:
2276                    info.append("\n## Total pending limit-orders: [0]\n")
2277
2278                # --- Show stop orders section:
2279                if view["stat"]["stopOrders"]:
2280                    info.extend([
2281                        "\n## Opened stop-orders: [{}]\n".format(len(view["stat"]["stopOrders"])),
2282                        "\n| Ticker [FIGI]               | Stop order ID                        | Lots   | Current price (% delta) | Target price  | Limit price   | Action    | Type        | Expire type  | Create date (UTC)   | Expiration (UTC)    |\n",
2283                        "|-----------------------------|--------------------------------------|--------|-------------------------|---------------|---------------|-----------|-------------|--------------|---------------------|---------------------|\n",
2284                    ])
2285
2286                    for item in view["stat"]["stopOrders"]:
2287                        info.append("| {:<27} | {:<14} | {:<6} | {:>23} | {:>13} | {:>13} | {:<9} | {:<11} | {:<12} | {:<19} | {:<19} |\n".format(
2288                            "{} [{}]".format(item["ticker"], item["figi"]),
2289                            item["orderID"],
2290                            item["lotsRequested"],
2291                            "{} {} ({}{:.2f}%)".format(
2292                                "{}".format(item["currentPrice"]) if isinstance(item["currentPrice"], str) else "{:.2f}".format(float(item["currentPrice"])),
2293                                item["baseCurrencyName"],
2294                                "+" if item["percentChanges"] > 0 else "",
2295                                float(item["percentChanges"]),
2296                            ),
2297                            "{:.2f} {}".format(float(item["targetPrice"]), item["baseCurrencyName"]),
2298                            "{:.2f} {}".format(float(item["limitPrice"]), item["baseCurrencyName"]) if item["limitPrice"] and item["limitPrice"] != item["targetPrice"] else TKS_ORDER_TYPES["ORDER_TYPE_MARKET"],
2299                            item["action"],
2300                            item["type"],
2301                            item["expType"],
2302                            item["createDate"],
2303                            item["expDate"],
2304                        ))
2305
2306                else:
2307                    info.append("\n## Total stop-orders: [0]\n")
2308
2309            if details in ["full", "analytics"]:
2310                # -- Show analytics section:
2311                if view["stat"]["portfolioCostRUB"] > 0:
2312                    info.extend([
2313                        "\n# Analytics\n\n"
2314                        "* **Actual on date:** [{} UTC]\n".format(actualOnDate),
2315                        "* **Current total portfolio cost:** {:.2f} RUB\n".format(view["stat"]["portfolioCostRUB"]),
2316                        "* **Changes:** {}{:.2f} RUB ({}{:.2f}%)\n".format(
2317                            "+" if view["stat"]["totalChangesRUB"] > 0 else "",
2318                            view["stat"]["totalChangesRUB"],
2319                            "+" if view["stat"]["totalChangesPercentRUB"] > 0 else "",
2320                            view["stat"]["totalChangesPercentRUB"],
2321                        ),
2322                        "\n## Portfolio distribution by assets\n"
2323                        "\n| Type                               | Uniques | Percent | Current cost       |\n",
2324                        "|------------------------------------|---------|---------|--------------------|\n",
2325                    ])
2326
2327                    for key in view["analytics"]["distrByAssets"].keys():
2328                        if view["analytics"]["distrByAssets"][key]["cost"] > 0:
2329                            info.append("| {:<34} | {:<7} | {:<7} | {:<18} |\n".format(
2330                                key,
2331                                view["analytics"]["distrByAssets"][key]["uniques"],
2332                                "{:.2f}%".format(view["analytics"]["distrByAssets"][key]["percent"]),
2333                                "{:.2f} rub".format(view["analytics"]["distrByAssets"][key]["cost"]),
2334                            ))
2335
2336                    aSepLine = "|----------------------------------------------|---------|--------------------|\n"
2337
2338                    info.extend([
2339                        "\n## Portfolio distribution by companies\n"
2340                        "\n| Company                                      | Percent | Current cost       |\n",
2341                        aSepLine,
2342                    ])
2343
2344                    for company in view["analytics"]["distrByCompanies"].keys():
2345                        if view["analytics"]["distrByCompanies"][company]["cost"] > 0:
2346                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2347                                "{}{}".format(
2348                                    "[{}] ".format(view["analytics"]["distrByCompanies"][company]["ticker"]) if view["analytics"]["distrByCompanies"][company]["ticker"] else "",
2349                                    company,
2350                                ),
2351                                "{:.2f}%".format(view["analytics"]["distrByCompanies"][company]["percent"]),
2352                                "{:.2f} rub".format(view["analytics"]["distrByCompanies"][company]["cost"]),
2353                            ))
2354
2355                    info.extend([
2356                        "\n## Portfolio distribution by sectors\n"
2357                        "\n| Sector                                       | Percent | Current cost       |\n",
2358                        aSepLine,
2359                    ])
2360
2361                    for sector in view["analytics"]["distrBySectors"].keys():
2362                        if view["analytics"]["distrBySectors"][sector]["cost"] > 0:
2363                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2364                                sector,
2365                                "{:.2f}%".format(view["analytics"]["distrBySectors"][sector]["percent"]),
2366                                "{:.2f} rub".format(view["analytics"]["distrBySectors"][sector]["cost"]),
2367                            ))
2368
2369                    info.extend([
2370                        "\n## Portfolio distribution by currencies\n"
2371                        "\n| Instruments currencies                       | Percent | Current cost       |\n",
2372                        aSepLine,
2373                    ])
2374
2375                    for curr in view["analytics"]["distrByCurrencies"].keys():
2376                        if view["analytics"]["distrByCurrencies"][curr]["cost"] > 0:
2377                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2378                                "[{}] {}".format(curr, view["analytics"]["distrByCurrencies"][curr]["name"]),
2379                                "{:.2f}%".format(view["analytics"]["distrByCurrencies"][curr]["percent"]),
2380                                "{:.2f} rub".format(view["analytics"]["distrByCurrencies"][curr]["cost"]),
2381                            ))
2382
2383                    info.extend([
2384                        "\n## Portfolio distribution by countries\n"
2385                        "\n| Assets by country                            | Percent | Current cost       |\n",
2386                        aSepLine,
2387                    ])
2388
2389                    for country in view["analytics"]["distrByCountries"].keys():
2390                        if view["analytics"]["distrByCountries"][country]["cost"] > 0:
2391                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2392                                country,
2393                                "{:.2f}%".format(view["analytics"]["distrByCountries"][country]["percent"]),
2394                                "{:.2f} rub".format(view["analytics"]["distrByCountries"][country]["cost"]),
2395                            ))
2396
2397            if details in ["full", "calendar"]:
2398                # -- Show bonds payment calendar section:
2399                if view["stat"]["Bonds"]:
2400                    bondTickers = [item["ticker"] for item in view["stat"]["Bonds"]]
2401                    view["analytics"]["bondsCalendar"] = self.ExtendBondsData(instruments=bondTickers, xlsx=False)
2402                    info.append("\n" + self.ShowBondsCalendar(extBonds=view["analytics"]["bondsCalendar"], show=False))
2403
2404                else:
2405                    info.append("\n# Bond payments calendar\n\nNo bonds in the portfolio to create payments calendar\n")
2406
2407            infoText = "".join(info)
2408
2409            if show and not onlyFiles:
2410                uLogger.info(infoText)
2411
2412            if details == "full" and self.overviewFile:
2413                filename = self.overviewFile
2414
2415            elif details == "digest" and self.overviewDigestFile:
2416                filename = self.overviewDigestFile
2417
2418            elif details == "positions" and self.overviewPositionsFile:
2419                filename = self.overviewPositionsFile
2420
2421            elif details == "orders" and self.overviewOrdersFile:
2422                filename = self.overviewOrdersFile
2423
2424            elif details == "analytics" and self.overviewAnalyticsFile:
2425                filename = self.overviewAnalyticsFile
2426
2427            elif details == "calendar" and self.overviewBondsCalendarFile:
2428                filename = self.overviewBondsCalendarFile
2429
2430            else:
2431                filename = ""
2432
2433            if filename and (show or onlyFiles):
2434                with open(filename, "w", encoding="UTF-8") as fH:
2435                    fH.write(infoText)
2436
2437                uLogger.info("Client's portfolio was saved to file: [{}]".format(os.path.abspath(filename)))
2438
2439                if self.useHTMLReports:
2440                    htmlFilePath = filename.replace(".md", ".html") if filename.endswith(".md") else filename + ".html"
2441                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
2442                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Client's portfolio", commonCSS=COMMON_CSS, markdown=infoText))
2443
2444                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
2445
2446        return view
2447
2448    def Deals(self, start: str = None, end: str = None, show: bool = False, showCancelled: bool = True, onlyFiles=False) -> tuple[list[dict], dict]:
2449        """
2450        Returns history operations between two given dates for current `accountId`.
2451        If `reportFile` string is not empty then also save human-readable report.
2452        Shows some statistical data of closed positions.
2453
2454        :param start: see docstring in `TradeRoutines.GetDatesAsString()` method.
2455        :param end: see docstring in `TradeRoutines.GetDatesAsString()` method.
2456        :param show: if `True` then also prints all records to the console.
2457        :param showCancelled: if `False` then remove information about cancelled operations from the deals report.
2458        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
2459        :return: original list of dictionaries with history of deals records from API ("operations" key):
2460                 https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations
2461                 and dictionary with custom stats: operations in different currencies, withdrawals, incomes etc.
2462        """
2463        if self.accountId is None or not self.accountId:
2464            uLogger.error("Variable `accountId` must be defined for using this method!")
2465            raise Exception("Account ID required")
2466
2467        startDate, endDate = GetDatesAsString(start, end, userFormat=TKS_DATE_FORMAT, outputFormat=TKS_DATE_TIME_FORMAT)  # Example: ("2000-01-01T00:00:00Z", "2022-12-31T23:59:59Z")
2468
2469        uLogger.debug("Requesting history of a client's operations. Wait, please...")
2470
2471        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations
2472        dealsURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetOperations"
2473        self.body = str({"accountId": self.accountId, "from": startDate, "to": endDate})
2474        ops = self.SendAPIRequest(dealsURL, reqType="POST")["operations"]  # list of dict: operations returns by broker
2475        customStat = {}  # custom statistics in additional to responseJSON
2476
2477        # --- output report in human-readable format:
2478        if self.reportFile and (show or onlyFiles):
2479            splitLine1 = "|                            |                               |                              |                      |                        |\n"  # Summary section
2480            splitLine2 = "|                     |              |              |            |           |                 |            |                                                                    |\n"  # Operations section
2481            nextDay = ""
2482
2483            info = ["# Client's operations\n\n* **Period:** from [{}] to [{}]\n\n## Summary (operations executed only)\n\n".format(startDate.split("T")[0], endDate.split("T")[0])]
2484
2485            if len(ops) > 0:
2486                customStat = {
2487                    "opsCount": 0,  # total operations count
2488                    "buyCount": 0,  # buy operations
2489                    "sellCount": 0,  # sell operations
2490                    "buyTotal": {"rub": 0.},  # Buy sums in different currencies
2491                    "sellTotal": {"rub": 0.},  # Sell sums in different currencies
2492                    "payIn": {"rub": 0.},  # Deposit brokerage account
2493                    "payOut": {"rub": 0.},  # Withdrawals
2494                    "divs": {"rub": 0.},  # Dividends income
2495                    "coupons": {"rub": 0.},  # Coupon's income
2496                    "brokerCom": {"rub": 0.},  # Service commissions
2497                    "serviceCom": {"rub": 0.},  # Service commissions
2498                    "marginCom": {"rub": 0.},  # Margin commissions
2499                    "allTaxes": {"rub": 0.},  # Sum of withholding taxes and corrections
2500                }
2501
2502                # --- calculating statistics depends on operations type in TKS_OPERATION_TYPES:
2503                for item in ops:
2504                    if item["state"] == "OPERATION_STATE_EXECUTED":
2505                        payment = NanoToFloat(item["payment"]["units"], item["payment"]["nano"])
2506
2507                        # count buy operations:
2508                        if "_BUY" in item["operationType"]:
2509                            customStat["buyCount"] += 1
2510
2511                            if item["payment"]["currency"] in customStat["buyTotal"].keys():
2512                                customStat["buyTotal"][item["payment"]["currency"]] += payment
2513
2514                            else:
2515                                customStat["buyTotal"][item["payment"]["currency"]] = payment
2516
2517                        # count sell operations:
2518                        elif "_SELL" in item["operationType"]:
2519                            customStat["sellCount"] += 1
2520
2521                            if item["payment"]["currency"] in customStat["sellTotal"].keys():
2522                                customStat["sellTotal"][item["payment"]["currency"]] += payment
2523
2524                            else:
2525                                customStat["sellTotal"][item["payment"]["currency"]] = payment
2526
2527                        # count incoming operations:
2528                        elif item["operationType"] in ["OPERATION_TYPE_INPUT"]:
2529                            if item["payment"]["currency"] in customStat["payIn"].keys():
2530                                customStat["payIn"][item["payment"]["currency"]] += payment
2531
2532                            else:
2533                                customStat["payIn"][item["payment"]["currency"]] = payment
2534
2535                        # count withdrawals operations:
2536                        elif item["operationType"] in ["OPERATION_TYPE_OUTPUT"]:
2537                            if item["payment"]["currency"] in customStat["payOut"].keys():
2538                                customStat["payOut"][item["payment"]["currency"]] += payment
2539
2540                            else:
2541                                customStat["payOut"][item["payment"]["currency"]] = payment
2542
2543                        # count dividends income:
2544                        elif item["operationType"] in ["OPERATION_TYPE_DIVIDEND", "OPERATION_TYPE_DIVIDEND_TRANSFER", "OPERATION_TYPE_DIV_EXT"]:
2545                            if item["payment"]["currency"] in customStat["divs"].keys():
2546                                customStat["divs"][item["payment"]["currency"]] += payment
2547
2548                            else:
2549                                customStat["divs"][item["payment"]["currency"]] = payment
2550
2551                        # count coupon's income:
2552                        elif item["operationType"] in ["OPERATION_TYPE_COUPON", "OPERATION_TYPE_BOND_REPAYMENT_FULL", "OPERATION_TYPE_BOND_REPAYMENT"]:
2553                            if item["payment"]["currency"] in customStat["coupons"].keys():
2554                                customStat["coupons"][item["payment"]["currency"]] += payment
2555
2556                            else:
2557                                customStat["coupons"][item["payment"]["currency"]] = payment
2558
2559                        # count broker commissions:
2560                        elif item["operationType"] in ["OPERATION_TYPE_BROKER_FEE", "OPERATION_TYPE_SUCCESS_FEE", "OPERATION_TYPE_TRACK_MFEE", "OPERATION_TYPE_TRACK_PFEE"]:
2561                            if item["payment"]["currency"] in customStat["brokerCom"].keys():
2562                                customStat["brokerCom"][item["payment"]["currency"]] += payment
2563
2564                            else:
2565                                customStat["brokerCom"][item["payment"]["currency"]] = payment
2566
2567                        # count service commissions:
2568                        elif item["operationType"] in ["OPERATION_TYPE_SERVICE_FEE"]:
2569                            if item["payment"]["currency"] in customStat["serviceCom"].keys():
2570                                customStat["serviceCom"][item["payment"]["currency"]] += payment
2571
2572                            else:
2573                                customStat["serviceCom"][item["payment"]["currency"]] = payment
2574
2575                        # count margin commissions:
2576                        elif item["operationType"] in ["OPERATION_TYPE_MARGIN_FEE"]:
2577                            if item["payment"]["currency"] in customStat["marginCom"].keys():
2578                                customStat["marginCom"][item["payment"]["currency"]] += payment
2579
2580                            else:
2581                                customStat["marginCom"][item["payment"]["currency"]] = payment
2582
2583                        # count withholding taxes:
2584                        elif "_TAX" in item["operationType"]:
2585                            if item["payment"]["currency"] in customStat["allTaxes"].keys():
2586                                customStat["allTaxes"][item["payment"]["currency"]] += payment
2587
2588                            else:
2589                                customStat["allTaxes"][item["payment"]["currency"]] = payment
2590
2591                        else:
2592                            continue
2593
2594                customStat["opsCount"] += customStat["buyCount"] + customStat["sellCount"]
2595
2596                # --- view "Actions" lines:
2597                info.extend([
2598                    "| Report sections            |                               |                              |                      |                        |\n",
2599                    "|----------------------------|-------------------------------|------------------------------|----------------------|------------------------|\n",
2600                    "| **Actions:**               | Trades: {:<21} | Trading volumes:             |                      |                        |\n".format(customStat["opsCount"]),
2601                    "|                            |   Buy: {:<22} | {:<28} |                      |                        |\n".format(
2602                        "{} ({:.1f}%)".format(customStat["buyCount"], 100 * customStat["buyCount"] / customStat["opsCount"]) if customStat["opsCount"] != 0 else 0,
2603                        "  rub, buy: {:<16}".format("{:.2f}".format(customStat["buyTotal"]["rub"])) if customStat["buyTotal"]["rub"] != 0 else "  —",
2604                    ),
2605                    "|                            |   Sell: {:<21} | {:<28} |                      |                        |\n".format(
2606                        "{} ({:.1f}%)".format(customStat["sellCount"], 100 * customStat["sellCount"] / customStat["opsCount"]) if customStat["opsCount"] != 0 else 0,
2607                        "  rub, sell: {:<13}".format("+{:.2f}".format(customStat["sellTotal"]["rub"])) if customStat["sellTotal"]["rub"] != 0 else "  —",
2608                    ),
2609                ])
2610
2611                opsKeys = sorted(list(set(list(customStat["buyTotal"].keys()) + list(customStat["sellTotal"].keys()))))
2612                for key in opsKeys:
2613                    if key == "rub":
2614                        continue
2615
2616                    info.extend([
2617                        "|                            |                               | {:<28} |                      |                        |\n".format(
2618                            "  {}, buy: {:<16}".format(key, "{:.2f}".format(customStat["buyTotal"][key]) if key and key in customStat["buyTotal"].keys() and customStat["buyTotal"][key] != 0 else 0)
2619                        ),
2620                        "|                            |                               | {:<28} |                      |                        |\n".format(
2621                            "  {}, sell: {:<13}".format(key, "+{:.2f}".format(customStat["sellTotal"][key]) if key and key in customStat["sellTotal"].keys() and customStat["sellTotal"][key] != 0 else 0)
2622                        ),
2623                    ])
2624
2625                info.append(splitLine1)
2626
2627                def _InfoStr(data1: dict, data2: dict, data3: dict, data4: dict, cur: str = "") -> str:
2628                    return "|                            | {:<29} | {:<28} | {:<20} | {:<22} |\n".format(
2629                            "  {}: {}{:.2f}".format(cur, "+" if data1[cur] > 0 else "", data1[cur]) if cur and cur in data1.keys() and data1[cur] != 0 else "  —",
2630                            "  {}: {}{:.2f}".format(cur, "+" if data2[cur] > 0 else "", data2[cur]) if cur and cur in data2.keys() and data2[cur] != 0 else "  —",
2631                            "  {}: {}{:.2f}".format(cur, "+" if data3[cur] > 0 else "", data3[cur]) if cur and cur in data3.keys() and data3[cur] != 0 else "  —",
2632                            "  {}: {}{:.2f}".format(cur, "+" if data4[cur] > 0 else "", data4[cur]) if cur and cur in data4.keys() and data4[cur] != 0 else "  —",
2633                    )
2634
2635                # --- view "Payments" lines:
2636                info.append("| **Payments:**              | Deposit on broker account:    | Withdrawals:                 | Dividends income:    | Coupons income:        |\n")
2637                paymentsKeys = sorted(list(set(list(customStat["payIn"].keys()) + list(customStat["payOut"].keys()) + list(customStat["divs"].keys()) + list(customStat["coupons"].keys()))))
2638
2639                for key in paymentsKeys:
2640                    info.append(_InfoStr(customStat["payIn"], customStat["payOut"], customStat["divs"], customStat["coupons"], key))
2641
2642                info.append(splitLine1)
2643
2644                # --- view "Commissions and taxes" lines:
2645                info.append("| **Commissions and taxes:** | Broker commissions:           | Service commissions:         | Margin commissions:  | All taxes/corrections: |\n")
2646                comKeys = sorted(list(set(list(customStat["brokerCom"].keys()) + list(customStat["serviceCom"].keys()) + list(customStat["marginCom"].keys()) + list(customStat["allTaxes"].keys()))))
2647
2648                for key in comKeys:
2649                    info.append(_InfoStr(customStat["brokerCom"], customStat["serviceCom"], customStat["marginCom"], customStat["allTaxes"], key))
2650
2651                info.extend([
2652                    "\n## All operations{}\n\n".format("" if showCancelled else " (without cancelled status)"),
2653                    "| Date and time       | FIGI         | Ticker       | Asset      | Value     | Payment         | Status     | Operation type                                                     |\n",
2654                    "|---------------------|--------------|--------------|------------|-----------|-----------------|------------|--------------------------------------------------------------------|\n",
2655                ])
2656
2657            else:
2658                info.append("Broker returned no operations during this period\n")
2659
2660            # --- view "Operations" section:
2661            for item in ops:
2662                if not showCancelled and TKS_OPERATION_STATES[item["state"]] == TKS_OPERATION_STATES["OPERATION_STATE_CANCELED"]:
2663                    continue
2664
2665                else:
2666                    self._figi = item["figi"]
2667                    payment = NanoToFloat(item["payment"]["units"], item["payment"]["nano"])
2668                    instrument = self.SearchByFIGI(requestPrice=False) if self._figi else {}
2669
2670                    # group of deals during one day:
2671                    if nextDay and item["date"].split("T")[0] != nextDay:
2672                        info.append(splitLine2)
2673                        nextDay = ""
2674
2675                    else:
2676                        nextDay = item["date"].split("T")[0]  # saving current day for splitting
2677
2678                    info.append("| {:<19} | {:<12} | {:<12} | {:<10} | {:<9} | {:>15} | {:<10} | {:<66} |\n".format(
2679                        item["date"].replace("T", " ").replace("Z", "").split(".")[0],
2680                        self._figi if self._figi else "—",
2681                        instrument["ticker"] if instrument else "—",
2682                        instrument["type"] if instrument else "—",
2683                        item["quantity"] if int(item["quantity"]) > 0 else "—",
2684                        "{}{:.2f} {}".format("+" if payment > 0 else "", payment, item["payment"]["currency"]) if payment != 0 else "—",
2685                        TKS_OPERATION_STATES[item["state"]],
2686                        TKS_OPERATION_TYPES[item["operationType"]],
2687                    ))
2688
2689            infoText = "".join(info)
2690
2691            if show and not onlyFiles:
2692                if self.moreDebug:
2693                    uLogger.debug("Records about history of a client's operations successfully received")
2694
2695                uLogger.info(infoText)
2696
2697            if self.reportFile and (show or onlyFiles):
2698                with open(self.reportFile, "w", encoding="UTF-8") as fH:
2699                    fH.write(infoText)
2700
2701                uLogger.info("History of a client's operations are saved to file: [{}]".format(os.path.abspath(self.reportFile)))
2702
2703                if self.useHTMLReports:
2704                    htmlFilePath = self.reportFile.replace(".md", ".html") if self.reportFile.endswith(".md") else self.reportFile + ".html"
2705                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
2706                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Client's operations", commonCSS=COMMON_CSS, markdown=infoText))
2707
2708                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
2709
2710        return ops, customStat
2711
2712    def History(self, start: str = None, end: str = None, interval: str = "hour", onlyMissing: bool = False, csvSep: str = ",", show: bool = False, onlyFiles=False) -> pd.DataFrame:
2713        """
2714        This method returns last history candles of the current instrument defined by `ticker` or `figi` (FIGI id).
2715
2716        History returned between two given dates: `start` and `end`. Minimum requested date in the past is `1970-01-01`.
2717        Warning! Broker server used ISO UTC time by default.
2718
2719        If `historyFile` is not `None` then method save history to file, otherwise return only Pandas DataFrame.
2720        Also, `historyFile` used to update history with `onlyMissing` parameter.
2721
2722        See also: `LoadHistory()` and `ShowHistoryChart()` methods.
2723
2724        :param start: see docstring in `TradeRoutines.GetDatesAsString()` method.
2725        :param end: see docstring in `TradeRoutines.GetDatesAsString()` method.
2726        :param interval: this is a candle interval. Current available values are `"1min"`, `"5min"`, `"15min"`,
2727                         `"hour"`, `"day"`. Default: `"hour"`.
2728        :param onlyMissing: if `True` then add only last missing candles, do not request all history length from `start`.
2729                            False by default. Warning! History appends only from last candle to current time
2730                            with always update last candle!
2731        :param csvSep: separator if csv-file is used, `,` by default.
2732        :param show: if `True` then also prints Pandas DataFrame to the console.
2733        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
2734        :return: Pandas DataFrame with prices history. Headers of columns are defined by default:
2735                 `["date", "time", "open", "high", "low", "close", "volume"]`.
2736        """
2737        strStartDate, strEndDate = GetDatesAsString(start, end, userFormat=TKS_DATE_FORMAT, outputFormat=TKS_DATE_TIME_FORMAT)  # example: ("2020-01-01T00:00:00Z", "2022-12-31T23:59:59Z")
2738        headers = ["date", "time", "open", "high", "low", "close", "volume"]  # sequence and names of column headers
2739        history = None  # empty pandas object for history
2740
2741        if interval not in TKS_CANDLE_INTERVALS.keys():
2742            uLogger.error("Interval parameter must be string with current available values: `1min`, `5min`, `15min`, `hour` and `day`.")
2743            raise Exception("Incorrect value")
2744
2745        if not (self._ticker or self._figi):
2746            uLogger.error("Ticker or FIGI must be defined!")
2747            raise Exception("Ticker or FIGI required")
2748
2749        if self._ticker and not self._figi:
2750            instrumentByTicker = self.SearchByTicker(requestPrice=False)
2751            self._figi = instrumentByTicker["figi"] if instrumentByTicker else ""
2752
2753        if self._figi and not self._ticker:
2754            instrumentByFIGI = self.SearchByFIGI(requestPrice=False)
2755            self._ticker = instrumentByFIGI["ticker"] if instrumentByFIGI else ""
2756
2757        dtStart = datetime.strptime(strStartDate, TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc())  # datetime object from start time string
2758        dtEnd = datetime.strptime(strEndDate, TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc())  # datetime object from end time string
2759        if interval.lower() != "day":
2760            dtEnd += timedelta(seconds=1)  # adds 1 sec for requests, because day end returned by `TradeRoutines.GetDatesAsString()` is 23:59:59
2761
2762        delta = dtEnd - dtStart  # current UTC time minus last time in file
2763        deltaMinutes = delta.days * 1440 + delta.seconds // 60  # minutes between start and end dates
2764
2765        # calculate history length in candles:
2766        length = deltaMinutes // TKS_CANDLE_INTERVALS[interval][1]
2767        if deltaMinutes % TKS_CANDLE_INTERVALS[interval][1] > 0:
2768            length += 1  # to avoid fraction time
2769
2770        # calculate data blocks count:
2771        blocks = 1 if length < TKS_CANDLE_INTERVALS[interval][2] else 1 + length // TKS_CANDLE_INTERVALS[interval][2]
2772
2773        uLogger.debug("Requesting history candlesticks, ticker: [{}], FIGI: [{}]. Wait, please...".format(self._ticker, self._figi))
2774        if self.moreDebug:
2775            uLogger.debug("Original requested time period in local time: from [{}] to [{}]".format(start, end))
2776            uLogger.debug("Requested time period is about from [{}] UTC to [{}] UTC".format(strStartDate, strEndDate))
2777            uLogger.debug("Calculated history length: [{}], interval: [{}]".format(length, interval))
2778            uLogger.debug("Data blocks, count: [{}], max candles in block: [{}]".format(blocks, TKS_CANDLE_INTERVALS[interval][2]))
2779
2780        tempOld = None  # pandas object for old history, if --only-missing key present
2781        lastTime = None  # datetime object of last old candle in file
2782
2783        if onlyMissing and self.historyFile is not None and self.historyFile and os.path.exists(self.historyFile):
2784            if self.moreDebug:
2785                uLogger.debug("--only-missing key present, add only last missing candles...")
2786                uLogger.debug("History file will be updated: [{}]".format(os.path.abspath(self.historyFile)))
2787
2788            tempOld = pd.read_csv(self.historyFile, sep=csvSep, header=None, names=headers)
2789
2790            tempOld["date"] = pd.to_datetime(tempOld["date"])  # load date "as is"
2791            tempOld["date"] = tempOld["date"].dt.strftime("%Y.%m.%d")  # convert date to string
2792            tempOld["time"] = pd.to_datetime(tempOld["time"])  # load time "as is"
2793            tempOld["time"] = tempOld["time"].dt.strftime("%H:%M")  # convert time to string
2794
2795            # get last datetime object from last string in file or minus 1 delta if file is empty:
2796            if len(tempOld) > 0:
2797                lastTime = datetime.strptime(tempOld.date.iloc[-1] + " " + tempOld.time.iloc[-1], "%Y.%m.%d %H:%M").replace(tzinfo=tzutc())
2798
2799            else:
2800                lastTime = dtEnd - timedelta(days=1)  # history file is empty, so last date set at -1 day
2801
2802            tempOld = tempOld[:-1]  # always remove last old candle because it may be incompletely at the current time
2803
2804        responseJSONs = []  # raw history blocks of data
2805
2806        blockEnd = dtEnd
2807        for item in range(blocks):
2808            tail = length % TKS_CANDLE_INTERVALS[interval][2] if item + 1 == blocks else TKS_CANDLE_INTERVALS[interval][2]
2809            blockStart = blockEnd - timedelta(minutes=TKS_CANDLE_INTERVALS[interval][1] * tail)
2810
2811            uLogger.debug("[Block #{}/{}] time period: [{}] UTC - [{}] UTC".format(
2812                item + 1, blocks, blockStart.strftime(TKS_DATE_TIME_FORMAT), blockEnd.strftime(TKS_DATE_TIME_FORMAT),
2813            ))
2814
2815            if blockStart == blockEnd:
2816                uLogger.debug("Skipped this zero-length block...")
2817
2818            else:
2819                # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetCandles
2820                historyURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetCandles"
2821                self.body = str({
2822                    "figi": self._figi,
2823                    "from": blockStart.strftime(TKS_DATE_TIME_FORMAT),
2824                    "to": blockEnd.strftime(TKS_DATE_TIME_FORMAT),
2825                    "interval": TKS_CANDLE_INTERVALS[interval][0]
2826                })
2827                responseJSON = self.SendAPIRequest(historyURL, reqType="POST", retry=1, pause=1)
2828
2829                if "code" in responseJSON.keys():
2830                    uLogger.debug("An issue occurred and block #{}/{} is empty".format(item + 1, blocks))
2831
2832                else:
2833                    if start is not None and (start.lower() == "yesterday" or start == end) and interval == "day" and len(responseJSON["candles"]) > 1:
2834                        responseJSON["candles"] = responseJSON["candles"][:-1]  # removes last candle for "yesterday" request
2835
2836                    responseJSONs = responseJSON["candles"] + responseJSONs  # add more old history behind newest dates
2837
2838            blockEnd = blockStart
2839
2840        printCount = len(responseJSONs)  # candles to show in console
2841        if responseJSONs:
2842            tempHistory = pd.DataFrame(
2843                data={
2844                    "date": [pd.to_datetime(item["time"]).astimezone(tzutc()) for item in responseJSONs],
2845                    "time": [pd.to_datetime(item["time"]).astimezone(tzutc()) for item in responseJSONs],
2846                    "open": [NanoToFloat(item["open"]["units"], item["open"]["nano"]) for item in responseJSONs],
2847                    "high": [NanoToFloat(item["high"]["units"], item["high"]["nano"]) for item in responseJSONs],
2848                    "low": [NanoToFloat(item["low"]["units"], item["low"]["nano"]) for item in responseJSONs],
2849                    "close": [NanoToFloat(item["close"]["units"], item["close"]["nano"]) for item in responseJSONs],
2850                    "volume": [int(item["volume"]) for item in responseJSONs],
2851                },
2852                index=range(len(responseJSONs)),
2853                columns=["date", "time", "open", "high", "low", "close", "volume"],
2854            )
2855            tempHistory["date"] = tempHistory["date"].dt.strftime("%Y.%m.%d")
2856            tempHistory["time"] = tempHistory["time"].dt.strftime("%H:%M")
2857
2858            # append only newest candles to old history if --only-missing key present:
2859            if onlyMissing and tempOld is not None and lastTime is not None:
2860                index = 0  # find start index in tempHistory data:
2861
2862                for i, item in tempHistory.iterrows():
2863                    curTime = datetime.strptime(item["date"] + " " + item["time"], "%Y.%m.%d %H:%M").replace(tzinfo=tzutc())
2864
2865                    if curTime == lastTime:
2866                        uLogger.debug("History will be updated starting from the date: [{}]".format(curTime.strftime(TKS_PRINT_DATE_TIME_FORMAT)))
2867                        index = i
2868                        printCount = index + 1
2869                        break
2870
2871                history = pd.concat([tempOld, tempHistory[index:]], ignore_index=True)
2872
2873            else:
2874                history = tempHistory  # if no `--only-missing` key then load full data from server
2875
2876            if self.moreDebug:
2877                uLogger.debug("Last 3 rows of received history:\n{}".format(pd.DataFrame.to_string(history[["date", "time", "open", "high", "low", "close", "volume"]][-3:], max_cols=20, index=False)))
2878
2879        if history is not None and not history.empty:
2880            if show and not onlyFiles:
2881                uLogger.info("Here's requested history between [{}] UTC and [{}] UTC, not-empty candles count: [{}]\n{}".format(
2882                    strStartDate.replace("T", " ").replace("Z", ""), strEndDate.replace("T", " ").replace("Z", ""), len(history[-printCount:]),
2883                    pd.DataFrame.to_string(history[["date", "time", "open", "high", "low", "close", "volume"]][-printCount:], max_cols=20, index=False),
2884                ))
2885
2886        else:
2887            uLogger.warning("Received an empty candles history!")
2888
2889        if self.historyFile is not None:
2890            if history is not None and not history.empty:
2891                history.to_csv(self.historyFile, sep=csvSep, index=False, header=False)
2892                uLogger.info("Ticker [{}], FIGI [{}], tf: [{}], history saved: [{}]".format(self._ticker, self._figi, interval, os.path.abspath(self.historyFile)))
2893
2894            else:
2895                uLogger.warning("Empty history received! File NOT updated: [{}]".format(os.path.abspath(self.historyFile)))
2896
2897        else:
2898            if self.moreDebug:
2899                uLogger.debug("--output key is not defined. Parsed history file not saved to file, only Pandas DataFrame returns.")
2900
2901        return history
2902
2903    def LoadHistory(self, filePath: str) -> pd.DataFrame:
2904        """
2905        Load candles history from csv-file and return Pandas DataFrame object.
2906
2907        See also: `History()` and `ShowHistoryChart()` methods.
2908
2909        :param filePath: path to csv-file to open.
2910        """
2911        loadedHistory = None  # init candles data object
2912
2913        uLogger.debug("Loading candles history with PriceGenerator module. Wait, please...")
2914
2915        if os.path.exists(filePath):
2916            loadedHistory = self.priceModel.LoadFromFile(filePath)  # load data and get chain of candles as Pandas DataFrame
2917
2918            tfStr = self.priceModel.FormattedDelta(
2919                self.priceModel.timeframe,
2920                "{days} days {hours}h {minutes}m {seconds}s",
2921            ) if self.priceModel.timeframe >= timedelta(days=1) else self.priceModel.FormattedDelta(
2922                self.priceModel.timeframe,
2923                "{hours}h {minutes}m {seconds}s",
2924            )
2925
2926            if loadedHistory is not None and not loadedHistory.empty:
2927                uLogger.info("Rows count loaded: [{}], detected timeframe of candles: [{}]. Showing some last rows:\n{}".format(
2928                    len(loadedHistory),
2929                    tfStr,
2930                    pd.DataFrame.to_string(loadedHistory[-10:], max_cols=20)),
2931                )
2932
2933            else:
2934                uLogger.warning("It was loaded an empty history! Path: [{}]".format(os.path.abspath(filePath)))
2935
2936        else:
2937            uLogger.error("File with candles history does not exist! Check the path: [{}]".format(filePath))
2938
2939        return loadedHistory
2940
2941    def ShowHistoryChart(self, candles: Union[str, pd.DataFrame] = None, interact: bool = True, openInBrowser: bool = False) -> None:
2942        """
2943        Render an HTML-file with interact or non-interact candlesticks chart. Candles may be path to the csv-file.
2944
2945        Self variable `htmlHistoryFile` can be use as html-file name to save interaction or non-interaction chart.
2946        Default: `index.html` (both for interact and non-interact candlesticks chart).
2947
2948        See also: `History()` and `LoadHistory()` methods.
2949
2950        :param candles: string to csv-file with candles in OHLCV-model or like Pandas Dataframe object.
2951        :param interact: if True (default) then chain of candlesticks will render as interactive Bokeh chart.
2952                         See examples: https://github.com/Tim55667757/PriceGenerator#overriding-parameters
2953                         If False then chain of candlesticks will render as not interactive Google Candlestick chart.
2954                         See examples: https://github.com/Tim55667757/PriceGenerator#statistics-and-chart-on-a-simple-template
2955        :param openInBrowser: if True then immediately open chart in default browser, otherwise only path to
2956                              html-file prints to console. False by default, to avoid issues with `permissions denied` to html-file.
2957        """
2958        if isinstance(candles, str):
2959            self.priceModel.prices = self.LoadHistory(filePath=candles)  # load candles chain from file
2960            self.priceModel.ticker = os.path.basename(candles)  # use filename as ticker name in PriceGenerator
2961
2962        elif isinstance(candles, pd.DataFrame):
2963            self.priceModel.prices = candles  # set candles chain from variable
2964            self.priceModel.ticker = self._ticker  # use current TKSBrokerAPI ticker as ticker name in PriceGenerator
2965
2966            if "datetime" not in candles.columns:
2967                self.priceModel.prices["datetime"] = pd.to_datetime(candles.date + ' ' + candles.time, utc=True)  # PriceGenerator uses "datetime" column with date and time
2968
2969        else:
2970            uLogger.error("`candles` variable must be path string to the csv-file with candles in OHLCV-model or like Pandas Dataframe object!")
2971            raise Exception("Incorrect value")
2972
2973        self.priceModel.horizon = len(self.priceModel.prices)  # use length of candles data as horizon in PriceGenerator
2974
2975        if interact:
2976            uLogger.debug("Rendering interactive candles chart. Wait, please...")
2977
2978            self.priceModel.RenderBokeh(fileName=self.htmlHistoryFile, viewInBrowser=openInBrowser)
2979
2980        else:
2981            uLogger.debug("Rendering non-interactive candles chart. Wait, please...")
2982
2983            self.priceModel.RenderGoogle(fileName=self.htmlHistoryFile, viewInBrowser=openInBrowser)
2984
2985        uLogger.info("Rendered candles chart: [{}]".format(os.path.abspath(self.htmlHistoryFile)))
2986
2987    def Trade(self, operation: str, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
2988        """
2989        Universal method to create market order and make deal at the current price for current `accountId`. Returns JSON data with response.
2990        If `tp` or `sl` > 0, then in additional will open stop-orders with "TP" and "SL" flags for `stopType` parameter.
2991
2992        See also: `Order()` docstring. More simple methods than `Trade()` are `Buy()` and `Sell()`.
2993
2994        :param operation: string "Buy" or "Sell".
2995        :param lots: volume, integer count of lots >= 1.
2996        :param tp: float > 0, target price for stop-order with "TP" type. It used as take profit parameter `targetPrice` in `self.Order()`.
2997        :param sl: float > 0, target price for stop-order with "SL" type. It used as stop loss parameter `targetPrice` in `self.Order()`.
2998        :param expDate: string "Undefined" by default or local date in future,
2999                        it is a string with format `%Y-%m-%d %H:%M:%S`.
3000        :return: JSON with response from broker server.
3001        """
3002        if self.accountId is None or not self.accountId:
3003            uLogger.error("Variable `accountId` must be defined for using this method!")
3004            raise Exception("Account ID required")
3005
3006        if operation is None or not operation or operation not in ("Buy", "Sell"):
3007            uLogger.error("You must define operation type only one of them: `Buy` or `Sell`!")
3008            raise Exception("Incorrect value")
3009
3010        if lots is None or lots < 1:
3011            uLogger.warning("You must define trade volume > 0: integer count of lots! For current operation lots reset to 1.")
3012            lots = 1
3013
3014        if tp is None or tp < 0:
3015            tp = 0
3016
3017        if sl is None or sl < 0:
3018            sl = 0
3019
3020        if expDate is None or not expDate:
3021            expDate = "Undefined"
3022
3023        if not (self._ticker or self._figi):
3024            uLogger.error("Ticker or FIGI must be defined!")
3025            raise Exception("Ticker or FIGI required")
3026
3027        instrument = self.SearchByTicker(requestPrice=True) if self._ticker else self.SearchByFIGI(requestPrice=True)
3028        self._ticker = instrument["ticker"]
3029        self._figi = instrument["figi"]
3030
3031        uLogger.debug("Opening [{}] market order: ticker [{}], FIGI [{}], lots [{}], TP [{:.4f}], SL [{:.4f}], expiration date of TP/SL orders [{}]. Wait, please...".format(operation, self._ticker, self._figi, lots, tp, sl, expDate))
3032
3033        openTradeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/PostOrder"
3034        self.body = str({
3035            "figi": self._figi,
3036            "quantity": str(lots),
3037            "direction": "ORDER_DIRECTION_BUY" if operation == "Buy" else "ORDER_DIRECTION_SELL",  # see: TKS_ORDER_DIRECTIONS
3038            "accountId": str(self.accountId),
3039            "orderType": "ORDER_TYPE_MARKET",  # see: TKS_ORDER_TYPES
3040        })
3041        response = self.SendAPIRequest(openTradeURL, reqType="POST", retry=0)
3042
3043        if "orderId" in response.keys():
3044            uLogger.info("[{}] market order [{}] was executed: ticker [{}], FIGI [{}], lots [{}]. Total order price: [{:.4f} {}] (with commission: [{:.2f} {}]). Average price of lot: [{:.2f} {}]".format(
3045                operation, response["orderId"],
3046                self._ticker, self._figi, lots,
3047                NanoToFloat(response["totalOrderAmount"]["units"], response["totalOrderAmount"]["nano"]), response["totalOrderAmount"]["currency"],
3048                NanoToFloat(response["initialCommission"]["units"], response["initialCommission"]["nano"]), response["initialCommission"]["currency"],
3049                NanoToFloat(response["executedOrderPrice"]["units"], response["executedOrderPrice"]["nano"]), response["executedOrderPrice"]["currency"],
3050            ))
3051
3052            if tp > 0:
3053                self.Order(operation="Sell" if operation == "Buy" else "Buy", orderType="Stop", lots=lots, targetPrice=tp, limitPrice=tp, stopType="TP", expDate=expDate)
3054
3055            if sl > 0:
3056                self.Order(operation="Sell" if operation == "Buy" else "Buy", orderType="Stop", lots=lots, targetPrice=sl, limitPrice=sl, stopType="SL", expDate=expDate)
3057
3058        else:
3059            uLogger.warning("Not `oK` status received! Market order not executed. See full debug log and try again open order later.")
3060
3061        return response
3062
3063    def Buy(self, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
3064        """
3065        More simple method than `Trade()`. Create `Buy` market order and make deal at the current price. Returns JSON data with response.
3066        If `tp` or `sl` > 0, then in additional will opens stop-orders with "TP" and "SL" flags for `stopType` parameter.
3067
3068        See also: `Order()` and `Trade()` docstrings.
3069
3070        :param lots: volume, integer count of lots >= 1.
3071        :param tp: float > 0, take profit price of stop-order.
3072        :param sl: float > 0, stop loss price of stop-order.
3073        :param expDate: it's a local date in future.
3074                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3075        :return: JSON with response from broker server.
3076        """
3077        return self.Trade(operation="Buy", lots=lots, tp=tp, sl=sl, expDate=expDate)
3078
3079    def Sell(self, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
3080        """
3081        More simple method than `Trade()`. Create `Sell` market order and make deal at the current price. Returns JSON data with response.
3082        If `tp` or `sl` > 0, then in additional will open stop-orders with "TP" and "SL" flags for `stopType` parameter.
3083
3084        See also: `Order()` and `Trade()` docstrings.
3085
3086        :param lots: volume, integer count of lots >= 1.
3087        :param tp: float > 0, take profit price of stop-order.
3088        :param sl: float > 0, stop loss price of stop-order.
3089        :param expDate: it's a local date in the future.
3090                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3091        :return: JSON with response from broker server.
3092        """
3093        return self.Trade(operation="Sell", lots=lots, tp=tp, sl=sl, expDate=expDate)
3094
3095    def CloseTrades(self, instruments: list[str], portfolio: dict = None) -> None:
3096        """
3097        Close position of given instruments.
3098
3099        :param instruments: list of instruments defined by tickers or FIGIs that must be closed.
3100        :param portfolio: pre-received dictionary with open trades, returned by `Overview()` method.
3101                         This avoids unnecessary downloading data from the server.
3102        """
3103        if instruments is None or not instruments:
3104            uLogger.error("List of tickers or FIGIs must be defined for using this method!")
3105            raise Exception("Ticker or FIGI required")
3106
3107        if isinstance(instruments, str):
3108            instruments = [instruments]
3109
3110        uniqueInstruments = self.GetUniqueFIGIs(instruments)
3111        if uniqueInstruments:
3112            if portfolio is None or not portfolio:
3113                portfolio = self.Overview(show=False)
3114
3115            allOpened = [item["figi"] for iType in TKS_INSTRUMENTS for item in portfolio["stat"][iType]]
3116            uLogger.debug("All opened instruments by it's FIGI: {}".format(", ".join(allOpened)))
3117
3118            for self._figi in uniqueInstruments:
3119                if self._figi not in allOpened:
3120                    uLogger.warning("Instrument with FIGI [{}] not in open positions list!".format(self._figi))
3121                    continue
3122
3123                # search open trade info about instrument by ticker:
3124                instrument = {}
3125                for iType in TKS_INSTRUMENTS:
3126                    if instrument:
3127                        break
3128
3129                    for item in portfolio["stat"][iType]:
3130                        if item["figi"] == self._figi:
3131                            instrument = item
3132                            break
3133
3134                if instrument:
3135                    self._ticker = instrument["ticker"]
3136                    self._figi = instrument["figi"]
3137
3138                    uLogger.debug("Closing trade of instrument: ticker [{}], FIGI[{}], lots [{}]{}. Wait, please...".format(
3139                        self._ticker,
3140                        self._figi,
3141                        int(instrument["volume"]),
3142                        ", blocked [{}]".format(instrument["blocked"]) if instrument["blocked"] > 0 else "",
3143                    ))
3144
3145                    tradeLots = abs(instrument["lots"]) - instrument["blocked"]  # available volumes in lots for close operation
3146
3147                    if tradeLots > 0:
3148                        if instrument["blocked"] > 0:
3149                            uLogger.warning("Just for your information: there are [{}] lots blocked for instrument [{}]! Available only [{}] lots to closing trade.".format(
3150                                instrument["blocked"],
3151                                self._ticker,
3152                                tradeLots,
3153                            ))
3154
3155                        # if direction is "Long" then we need sell, if direction is "Short" then we need buy:
3156                        self.Trade(operation="Sell" if instrument["direction"] == "Long" else "Buy", lots=tradeLots)
3157
3158                    else:
3159                        uLogger.warning("There are no available lots for instrument [{}] to closing trade at this moment! Try again later or cancel some orders.".format(self._ticker))
3160
3161    def CloseAllTrades(self, iType: str, portfolio: dict = None) -> None:
3162        """
3163        Close all positions of given instruments with defined type.
3164
3165        :param iType: type of the instruments that be closed, it must be one of supported types in TKS_INSTRUMENTS list.
3166        :param portfolio: pre-received dictionary with open trades, returned by `Overview()` method.
3167                         This avoids unnecessary downloading data from the server.
3168        """
3169        if iType not in TKS_INSTRUMENTS:
3170            uLogger.warning("Type of the instrument must be one of supported types: {}. Given: [{}]".format(", ".join(TKS_INSTRUMENTS), iType))
3171
3172        else:
3173            if portfolio is None or not portfolio:
3174                portfolio = self.Overview(show=False)
3175
3176            tickers = [item["ticker"] for item in portfolio["stat"][iType]]
3177            uLogger.debug("Instrument tickers with type [{}] that will be closed: {}".format(iType, tickers))
3178
3179            if tickers and portfolio:
3180                self.CloseTrades(tickers, portfolio)
3181
3182            else:
3183                uLogger.info("Instrument tickers with type [{}] not found, nothing to close.".format(iType))
3184
3185    def Order(self, operation: str, orderType: str, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3186        """
3187        Universal method to create market or limit orders with all available parameters for current `accountId`.
3188        See more simple methods: `BuyLimit()`, `BuyStop()`, `SellLimit()`, `SellStop()`.
3189
3190        If orderType is "Limit" then create pending limit-order below current price if operation is "Buy" and above
3191        current price if operation is "Sell". A limit order has no expiration date, it lasts until the end of the trading day.
3192
3193        Warning! If you try to create limit-order above current price if "Buy" or below current price if "Sell"
3194        then broker immediately open market order as you can do simple --buy or --sell operations!
3195
3196        If orderType is "Stop" then creates stop-order with any direction "Buy" or "Sell".
3197        When current price will go up or down to target price value then broker opens a limit order.
3198        Stop-order is opened with unlimited expiration date by default, or you can define expiration date with expDate parameter.
3199
3200        Only one attempt and no retry for opens order. If network issue occurred you can create new request.
3201
3202        :param operation: string "Buy" or "Sell".
3203        :param orderType: string "Limit" or "Stop".
3204        :param lots: volume, integer count of lots >= 1.
3205        :param targetPrice: target price > 0. This is open trade price for limit order.
3206        :param limitPrice: limit price >= 0. This parameter only makes sense for stop-order. If limitPrice = 0, then it set as targetPrice.
3207                           Broker will creates limit-order with price equal to limitPrice, when current price goes to target price of stop-order.
3208        :param stopType: string "Limit" by default. This parameter only makes sense for stop-order. There are 3 stop-order types
3209                         "SL", "TP", "Limit" for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3210                         Stop loss order always executed by market price.
3211        :param expDate: string "Undefined" by default or local date in future.
3212                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3213                        This date is converting to UTC format for server. This parameter only makes sense for stop-order.
3214                        A limit order has no expiration date, it lasts until the end of the trading day.
3215        :return: JSON with response from broker server.
3216        """
3217        if self.accountId is None or not self.accountId:
3218            uLogger.error("Variable `accountId` must be defined for using this method!")
3219            raise Exception("Account ID required")
3220
3221        if operation is None or not operation or operation not in ("Buy", "Sell"):
3222            uLogger.error("You must define operation type only one of them: `Buy` or `Sell`!")
3223            raise Exception("Incorrect value")
3224
3225        if orderType is None or not orderType or orderType not in ("Limit", "Stop"):
3226            uLogger.error("You must define order type only one of them: `Limit` or `Stop`!")
3227            raise Exception("Incorrect value")
3228
3229        if lots is None or lots < 1:
3230            uLogger.error("You must define trade volume > 0: integer count of lots!")
3231            raise Exception("Incorrect value")
3232
3233        if targetPrice is None or targetPrice <= 0:
3234            uLogger.error("Target price for limit-order must be greater than 0!")
3235            raise Exception("Incorrect value")
3236
3237        if limitPrice is None or limitPrice <= 0:
3238            limitPrice = targetPrice
3239
3240        if stopType is None or not stopType or stopType not in ("SL", "TP", "Limit"):
3241            stopType = "Limit"
3242
3243        if expDate is None or not expDate:
3244            expDate = "Undefined"
3245
3246        if not (self._ticker or self._figi):
3247            uLogger.error("Tocker or FIGI must be defined!")
3248            raise Exception("Ticker or FIGI required")
3249
3250        response = {}
3251        instrument = self.SearchByTicker(requestPrice=True) if self._ticker else self.SearchByFIGI(requestPrice=True)
3252        self._ticker = instrument["ticker"]
3253        self._figi = instrument["figi"]
3254
3255        if orderType == "Limit":
3256            uLogger.debug(
3257                "Creating pending limit-order: ticker [{}], FIGI [{}], action [{}], lots [{}] and the target price [{:.2f} {}]. Wait, please...".format(
3258                    self._ticker, self._figi,
3259                    operation, lots, targetPrice, instrument["currency"],
3260                ))
3261
3262            openOrderURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/PostOrder"
3263            self.body = str({
3264                "figi": self._figi,
3265                "quantity": str(lots),
3266                "price": FloatToNano(targetPrice),
3267                "direction": "ORDER_DIRECTION_BUY" if operation == "Buy" else "ORDER_DIRECTION_SELL",  # see: TKS_ORDER_DIRECTIONS
3268                "accountId": str(self.accountId),
3269                "orderType": "ORDER_TYPE_LIMIT",  # see: TKS_ORDER_TYPES
3270            })
3271            response = self.SendAPIRequest(openOrderURL, reqType="POST", retry=0)
3272
3273            if "orderId" in response.keys():
3274                uLogger.info(
3275                    "Limit-order [{}] was created: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{} {}]".format(
3276                        response["orderId"], self._ticker, self._figi, operation, lots,
3277                        "{:.4f}".format(targetPrice).rstrip("0").rstrip("."), instrument["currency"],
3278                    ))
3279
3280                if "lastPrice" in instrument["currentPrice"].keys() and instrument["currentPrice"]["lastPrice"]:
3281                    if operation == "Buy" and targetPrice > instrument["currentPrice"]["lastPrice"]:
3282                        uLogger.warning("Your order was executed as a market order, not as a limit order! Comment: because your target price [{:.2f} {}] was higher than current price [{:.2f} {}] broker immediately opened `Buy` market order, such as if you did simple `--buy` operation.".format(
3283                            targetPrice, instrument["currency"],
3284                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3285                        ))
3286
3287                    if operation == "Sell" and targetPrice < instrument["currentPrice"]["lastPrice"]:
3288                        uLogger.warning("Your order was executed as a market order, not as a limit order! Comment: because your target price [{:.2f} {}] was lower than current price [{:.2f} {}] broker immediately opened `Sell` market order, such as if you did simple `--sell` operation.".format(
3289                            targetPrice, instrument["currency"],
3290                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3291                        ))
3292
3293            else:
3294                uLogger.warning("Not `oK` status received! Limit order not opened. See full debug log and try again open order later.")
3295
3296        if orderType == "Stop":
3297            uLogger.debug(
3298                "Creating stop-order: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}], limit price [{:.2f} {}], stop-order type [{}] and local expiration date [{}]. Wait, please...".format(
3299                    self._ticker, self._figi,
3300                    operation, lots,
3301                    targetPrice, instrument["currency"],
3302                    limitPrice, instrument["currency"],
3303                    stopType, expDate,
3304                ))
3305
3306            openOrderURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/PostStopOrder"
3307            expDateUTC = "" if expDate == "Undefined" else datetime.strptime(expDate, TKS_PRINT_DATE_TIME_FORMAT).replace(tzinfo=tzlocal()).astimezone(tzutc()).strftime(TKS_DATE_TIME_FORMAT_EXT)
3308            stopOrderType = "STOP_ORDER_TYPE_STOP_LOSS" if stopType == "SL" else "STOP_ORDER_TYPE_TAKE_PROFIT" if stopType == "TP" else "STOP_ORDER_TYPE_STOP_LIMIT"
3309
3310            body = {
3311                "figi": self._figi,
3312                "quantity": str(lots),
3313                "price": FloatToNano(limitPrice),
3314                "stopPrice": FloatToNano(targetPrice),
3315                "direction": "STOP_ORDER_DIRECTION_BUY" if operation == "Buy" else "STOP_ORDER_DIRECTION_SELL",  # see: TKS_STOP_ORDER_DIRECTIONS
3316                "accountId": str(self.accountId),
3317                "expirationType": "STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_DATE" if expDateUTC else "STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_CANCEL",  # see: TKS_STOP_ORDER_EXPIRATION_TYPES
3318                "stopOrderType": stopOrderType,  # see: TKS_STOP_ORDER_TYPES
3319            }
3320
3321            if expDateUTC:
3322                body["expireDate"] = expDateUTC
3323
3324            self.body = str(body)
3325            response = self.SendAPIRequest(openOrderURL, reqType="POST", retry=0)
3326
3327            if "stopOrderId" in response.keys():
3328                uLogger.info(
3329                    "Stop-order [{}] was created: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{} {}], limit price [{} {}], stop-order type [{}] and expiration date [{} UTC]".format(
3330                        response["stopOrderId"], self._ticker, self._figi, operation, lots,
3331                        "{:.4f}".format(targetPrice).rstrip("0").rstrip("."), instrument["currency"],
3332                        "{:.4f}".format(limitPrice).rstrip("0").rstrip("."), instrument["currency"],
3333                        TKS_STOP_ORDER_TYPES[stopOrderType],
3334                        datetime.strptime(expDateUTC, TKS_DATE_TIME_FORMAT_EXT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT) if expDateUTC else TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_UNSPECIFIED"],
3335                    ))
3336
3337                if "lastPrice" in instrument["currentPrice"].keys() and instrument["currentPrice"]["lastPrice"]:
3338                    if operation == "Buy" and targetPrice < instrument["currentPrice"]["lastPrice"] and stopType != "TP":
3339                        uLogger.warning("The broker will cancel this order after some time. Comment: you placed the wrong stop order because the target buy price [{:.2f} {}] is lower than the current price [{:.2f} {}]. Also try to set up order type as `TP` if you want to place stop order at that price.".format(
3340                            targetPrice, instrument["currency"],
3341                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3342                        ))
3343
3344                    if operation == "Sell" and targetPrice > instrument["currentPrice"]["lastPrice"] and stopType != "TP":
3345                        uLogger.warning("The broker will cancel this order after some time. Comment: you placed the wrong stop order because the target sell price [{:.2f} {}] is higher than the current price [{:.2f} {}]. Also try to set up order type as `TP` if you want to place stop order at that price.".format(
3346                            targetPrice, instrument["currency"],
3347                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3348                        ))
3349
3350            else:
3351                uLogger.warning("Not `oK` status received! Stop order not opened. See full debug log and try again open order later.")
3352
3353        return response
3354
3355    def BuyLimit(self, lots: int, targetPrice: float) -> dict:
3356        """
3357        Create pending `Buy` limit-order (below current price). You must specify only 2 parameters:
3358        `lots` and `target price` to open buy limit-order. If you try to create buy limit-order above current price then
3359        broker immediately open `Buy` market order, such as if you do simple `--buy` operation!
3360        See also: `Order()` docstring.
3361
3362        :param lots: volume, integer count of lots >= 1.
3363        :param targetPrice: target price > 0. This is open trade price for limit order.
3364        :return: JSON with response from broker server.
3365        """
3366        return self.Order(operation="Buy", orderType="Limit", lots=lots, targetPrice=targetPrice)
3367
3368    def BuyStop(self, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3369        """
3370        Create `Buy` stop-order. You must specify at least 2 parameters: `lots` `target price` to open buy stop-order.
3371        In additional you can specify 3 parameters for buy stop-order: `limit price` >=0, `stop type` = Limit|SL|TP,
3372        `expiration date` = Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`. When current price will go up or down to
3373        target price value then broker opens a limit order. See also: `Order()` docstring.
3374
3375        :param lots: volume, integer count of lots >= 1.
3376        :param targetPrice: target price > 0. This is trigger price for buy stop-order.
3377        :param limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will creates limit-order
3378                           with price equal to limitPrice, when current price goes to target price of buy stop-order.
3379        :param stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit"
3380                         for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3381        :param expDate: string "Undefined" by default or local date in future.
3382                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3383                        This date is converting to UTC format for server.
3384        :return: JSON with response from broker server.
3385        """
3386        return self.Order(operation="Buy", orderType="Stop", lots=lots, targetPrice=targetPrice, limitPrice=limitPrice, stopType=stopType, expDate=expDate)
3387
3388    def SellLimit(self, lots: int, targetPrice: float) -> dict:
3389        """
3390        Create pending `Sell` limit-order (above current price). You must specify only 2 parameters:
3391        `lots` and `target price` to open sell limit-order. If you try to create sell limit-order below current price then
3392        broker immediately open `Sell` market order, such as if you do simple `--sell` operation!
3393        See also: `Order()` docstring.
3394
3395        :param lots: volume, integer count of lots >= 1.
3396        :param targetPrice: target price > 0. This is open trade price for limit order.
3397        :return: JSON with response from broker server.
3398        """
3399        return self.Order(operation="Sell", orderType="Limit", lots=lots, targetPrice=targetPrice)
3400
3401    def SellStop(self, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3402        """
3403        Create `Sell` stop-order. You must specify at least 2 parameters: `lots` `target price` to open sell stop-order.
3404        In additional you can specify 3 parameters for sell stop-order: `limit price` >=0, `stop type` = Limit|SL|TP,
3405        `expiration date` = Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`. When current price will go up or down to
3406        target price value then broker opens a limit order. See also: `Order()` docstring.
3407
3408        :param lots: volume, integer count of lots >= 1.
3409        :param targetPrice: target price > 0. This is trigger price for sell stop-order.
3410        :param limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will creates limit-order
3411                           with price equal to limitPrice, when current price goes to target price of sell stop-order.
3412        :param stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit"
3413                         for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3414        :param expDate: string "Undefined" by default or local date in future.
3415                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3416                        This date is converting to UTC format for server.
3417        :return: JSON with response from broker server.
3418        """
3419        return self.Order(operation="Sell", orderType="Stop", lots=lots, targetPrice=targetPrice, limitPrice=limitPrice, stopType=stopType, expDate=expDate)
3420
3421    def CloseOrders(self, orderIDs: list, allOrdersIDs: list = None, allStopOrdersIDs: list = None) -> None:
3422        """
3423        Cancel order or list of orders by its `orderId` or `stopOrderId` for current `accountId`.
3424
3425        :param orderIDs: list of integers with `orderId` or `stopOrderId`.
3426        :param allOrdersIDs: pre-received lists of all active pending limit orders.
3427                             This avoids unnecessary downloading data from the server.
3428        :param allStopOrdersIDs: pre-received lists of all active stop orders.
3429        """
3430        if self.accountId is None or not self.accountId:
3431            uLogger.error("Variable `accountId` must be defined for using this method!")
3432            raise Exception("Account ID required")
3433
3434        if orderIDs:
3435            if allOrdersIDs is None:
3436                rawOrders = self.RequestPendingOrders()
3437                allOrdersIDs = [item["orderId"] for item in rawOrders]  # all pending limit orders ID
3438
3439            if allStopOrdersIDs is None:
3440                rawStopOrders = self.RequestStopOrders()
3441                allStopOrdersIDs = [item["stopOrderId"] for item in rawStopOrders]  # all stop orders ID
3442
3443            for orderID in orderIDs:
3444                idInPendingOrders = orderID in allOrdersIDs
3445                idInStopOrders = orderID in allStopOrdersIDs
3446
3447                if not (idInPendingOrders or idInStopOrders):
3448                    uLogger.warning("Order not found by ID: [{}]. Maybe cancelled already? Check it with `--overview` key.".format(orderID))
3449                    continue
3450
3451                else:
3452                    if idInPendingOrders:
3453                        uLogger.debug("Cancelling pending order with ID: [{}]. Wait, please...".format(orderID))
3454
3455                        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_CancelOrder
3456                        self.body = str({"accountId": self.accountId, "orderId": orderID})
3457                        closeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/CancelOrder"
3458                        responseJSON = self.SendAPIRequest(closeURL, reqType="POST")
3459
3460                        if responseJSON and "time" in responseJSON.keys() and responseJSON["time"]:
3461                            if self.moreDebug:
3462                                uLogger.debug("Success time marker received from server: [{}] (UTC)".format(responseJSON["time"]))
3463
3464                            uLogger.info("Pending order with ID [{}] successfully cancel".format(orderID))
3465
3466                        else:
3467                            uLogger.warning("Unknown issue occurred when cancelling pending order with ID: [{}]. Check ID and try again.".format(orderID))
3468
3469                    elif idInStopOrders:
3470                        uLogger.debug("Cancelling stop order with ID: [{}]. Wait, please...".format(orderID))
3471
3472                        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_CancelStopOrder
3473                        self.body = str({"accountId": self.accountId, "stopOrderId": orderID})
3474                        closeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/CancelStopOrder"
3475                        responseJSON = self.SendAPIRequest(closeURL, reqType="POST")
3476
3477                        if responseJSON and "time" in responseJSON.keys() and responseJSON["time"]:
3478                            if self.moreDebug:
3479                                uLogger.debug("Success time marker received from server: [{}] (UTC)".format(responseJSON["time"]))
3480
3481                            uLogger.info("Stop order with ID [{}] successfully cancel".format(orderID))
3482
3483                        else:
3484                            uLogger.warning("Unknown issue occurred when cancelling stop order with ID: [{}]. Check ID and try again.".format(orderID))
3485
3486                    else:
3487                        continue
3488
3489    def CloseAllOrders(self) -> None:
3490        """
3491        Gets a list of open pending and stop orders and cancel it all.
3492        """
3493        rawOrders = self.RequestPendingOrders()
3494        allOrdersIDs = [item["orderId"] for item in rawOrders]  # all pending limit orders ID
3495        lenOrders = len(allOrdersIDs)
3496
3497        rawStopOrders = self.RequestStopOrders()
3498        allStopOrdersIDs = [item["stopOrderId"] for item in rawStopOrders]  # all stop orders ID
3499        lenSOrders = len(allStopOrdersIDs)
3500
3501        if lenOrders > 0 or lenSOrders > 0:
3502            uLogger.info("Found: [{}] opened pending and [{}] stop orders. Let's trying to cancel it all. Wait, please...".format(lenOrders, lenSOrders))
3503
3504            self.CloseOrders(allOrdersIDs + allStopOrdersIDs, allOrdersIDs, allStopOrdersIDs)
3505
3506        else:
3507            uLogger.info("Orders not found, nothing to cancel.")
3508
3509    def CloseAll(self, *args) -> None:
3510        """
3511        Close all available (not blocked) opened trades and orders.
3512
3513        Also, you can select one or more keywords case-insensitive:
3514        `orders`, `shares`, `bonds`, `etfs` and `futures` from `TKS_INSTRUMENTS` enum to specify trades type.
3515
3516        Currency positions you must close manually using buy or sell operations, `CloseTrades()` or `CloseAllTrades()` methods.
3517        """
3518        overview = self.Overview(show=False)  # get all open trades info
3519
3520        if len(args) == 0:
3521            uLogger.debug("Closing all available (not blocked) opened trades and orders. Currency positions you must closes manually using buy or sell operations! Wait, please...")
3522            self.CloseAllOrders()  # close all pending and stop orders
3523
3524            for iType in TKS_INSTRUMENTS:
3525                if iType != "Currencies":
3526                    self.CloseAllTrades(iType, overview)  # close all positions of instruments with same type without currencies
3527
3528        else:
3529            uLogger.debug("Closing all available {}. Currency positions you must closes manually using buy or sell operations! Wait, please...".format(list(args)))
3530            lowerArgs = [x.lower() for x in args]
3531
3532            if "orders" in lowerArgs:
3533                self.CloseAllOrders()  # close all pending and stop orders
3534
3535            for iType in TKS_INSTRUMENTS:
3536                if iType.lower() in lowerArgs and iType != "Currencies":
3537                    self.CloseAllTrades(iType, overview)  # close all positions of instruments with same type without currencies
3538
3539    def CloseAllByTicker(self, instrument: str) -> None:
3540        """
3541        Close all available (not blocked) opened trades and orders for one instrument defined by its ticker.
3542
3543        This method searches opened trade and orders of instrument throw all portfolio and then use
3544        `CloseTrades()` and `CloseOrders()` methods to close trade and cancel all orders for that instrument.
3545
3546        See also: `IsInLimitOrders()`, `GetLimitOrderIDs()`, `IsInStopOrders()`, `GetStopOrderIDs()`, `CloseTrades()` and `CloseOrders()`.
3547
3548        :param instrument: string with ticker.
3549        """
3550        if instrument is None or not instrument:
3551            uLogger.error("Ticker name must be defined for using this method!")
3552            raise Exception("Ticker required")
3553
3554        overview = self.Overview(show=False)  # get user portfolio with all open trades info
3555
3556        self._ticker = instrument  # try to set instrument as ticker
3557        self._figi = ""
3558
3559        limitAll = [item["orderID"] for item in overview["stat"]["orders"]]  # list of all pending limit order IDs
3560        stopAll = [item["orderID"] for item in overview["stat"]["stopOrders"]]  # list of all stop order IDs
3561
3562        if limitAll and self.IsInLimitOrders(portfolio=overview):
3563            uLogger.debug("Closing all opened pending limit orders for the instrument with ticker [{}]. Wait, please...")
3564            self.CloseOrders(orderIDs=self.GetLimitOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3565
3566        if stopAll and self.IsInStopOrders(portfolio=overview):
3567            uLogger.debug("Closing all opened stop orders for the instrument with ticker [{}]. Wait, please...")
3568            self.CloseOrders(orderIDs=self.GetStopOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3569
3570        if self.IsInPortfolio(portfolio=overview):
3571            uLogger.debug("Closing all available (not blocked) opened trade for the instrument with ticker [{}]. Wait, please...")
3572            self.CloseTrades(instruments=[instrument], portfolio=overview)
3573
3574    def CloseAllByFIGI(self, instrument: str) -> None:
3575        """
3576        Close all available (not blocked) opened trades and orders for one instrument defined by its FIGI id.
3577
3578        This method searches opened trade and orders of instrument throw all portfolio and then use
3579        `CloseTrades()` and `CloseOrders()` methods to close trade and cancel all orders for that instrument.
3580
3581        See also: `IsInLimitOrders()`, `GetLimitOrderIDs()`, `IsInStopOrders()`, `GetStopOrderIDs()`, `CloseTrades()` and `CloseOrders()`.
3582
3583        :param instrument: string with FIGI id.
3584        """
3585        if instrument is None or not instrument:
3586            uLogger.error("FIGI id must be defined for using this method!")
3587            raise Exception("FIGI required")
3588
3589        overview = self.Overview(show=False)  # get user portfolio with all open trades info
3590
3591        self._ticker = ""
3592        self._figi = instrument  # try to set instrument as FIGI id
3593
3594        limitAll = [item["orderID"] for item in overview["stat"]["orders"]]  # list of all pending limit order IDs
3595        stopAll = [item["orderID"] for item in overview["stat"]["stopOrders"]]  # list of all stop order IDs
3596
3597        if limitAll and self.IsInLimitOrders(portfolio=overview):
3598            uLogger.debug("Closing all opened pending limit orders for the instrument with FIGI [{}]. Wait, please...")
3599            self.CloseOrders(orderIDs=self.GetLimitOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3600
3601        if stopAll and self.IsInStopOrders(portfolio=overview):
3602            uLogger.debug("Closing all opened stop orders for the instrument with FIGI [{}]. Wait, please...")
3603            self.CloseOrders(orderIDs=self.GetStopOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3604
3605        if self.IsInPortfolio(portfolio=overview):
3606            uLogger.debug("Closing all available (not blocked) opened trade for the instrument with FIGI [{}]. Wait, please...")
3607            self.CloseTrades(instruments=[instrument], portfolio=overview)
3608
3609    @staticmethod
3610    def ParseOrderParameters(operation, **inputParameters):
3611        """
3612        Parse input dictionary of strings with order parameters and return dictionary with parameters to open all orders.
3613
3614        :param operation: string "Buy" or "Sell".
3615        :param inputParameters: this is dict of strings that looks like this
3616               `{"lots": "L_int,...", "prices": "P_float,..."}` where
3617               "lots" key: one or more lot values (integer numbers) to open with every limit-order
3618               "prices" key: one or more prices to open limit-orders
3619               Counts of values in lots and prices lists must be equals!
3620        :return: list of dictionaries with all lots and prices to open orders that looks like this `[{"lot": lots_1, "price": price_1}, {...}, ...]`
3621        """
3622        # TODO: update order grid work with api v2
3623        pass
3624        # uLogger.debug("Input parameters: {}".format(inputParameters))
3625        #
3626        # if operation is None or not operation or operation not in ("Buy", "Sell"):
3627        #     uLogger.error("You must define operation type: 'Buy' or 'Sell'!")
3628        #     raise Exception("Incorrect value")
3629        #
3630        # if "l" in inputParameters.keys():
3631        #     inputParameters["lots"] = inputParameters.pop("l")
3632        #
3633        # if "p" in inputParameters.keys():
3634        #     inputParameters["prices"] = inputParameters.pop("p")
3635        #
3636        # if "lots" not in inputParameters.keys() or "prices" not in inputParameters.keys():
3637        #     uLogger.error("Both of 'lots' and 'prices' keys must be define to open grid orders!")
3638        #     raise Exception("Incorrect value")
3639        #
3640        # lots = [int(item.strip()) for item in inputParameters["lots"].split(",")]
3641        # prices = [float(item.strip()) for item in inputParameters["prices"].split(",")]
3642        #
3643        # if len(lots) != len(prices):
3644        #     uLogger.error("'lots' and 'prices' lists must have equal length of values!")
3645        #     raise Exception("Incorrect value")
3646        #
3647        # uLogger.debug("Extracted parameters for orders:")
3648        # uLogger.debug("lots = {}".format(lots))
3649        # uLogger.debug("prices = {}".format(prices))
3650        #
3651        # # list of dictionaries with order's parameters: [{"lot": lots_1, "price": price_1}, {...}, ...]
3652        # result = [{"lot": lots[item], "price": prices[item]} for item in range(len(prices))]
3653        # uLogger.debug("Order parameters: {}".format(result))
3654        #
3655        # return result
3656
3657    def IsInPortfolio(self, portfolio: dict = None) -> bool:
3658        """
3659        Checks if instrument is in the user's portfolio. Instrument must be defined by `ticker` (highly priority) or `figi`.
3660
3661        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3662        :return: `True` if portfolio contains open position with given instrument, `False` otherwise.
3663        """
3664        result = False
3665        msg = "Instrument not defined!"
3666
3667        if portfolio is None or not portfolio:
3668            portfolio = self.Overview(show=False)
3669
3670        if self._ticker:
3671            uLogger.debug("Searching instrument with ticker [{}] throw opened positions list...".format(self._ticker))
3672            msg = "Instrument with ticker [{}] is not present in open positions".format(self._ticker)
3673
3674            for iType in TKS_INSTRUMENTS:
3675                for instrument in portfolio["stat"][iType]:
3676                    if instrument["ticker"] == self._ticker:
3677                        result = True
3678                        msg = "Instrument with ticker [{}] is present in open positions".format(self._ticker)
3679                        break
3680
3681        elif self._figi:
3682            uLogger.debug("Searching instrument with FIGI [{}] throw opened positions list...".format(self._figi))
3683            msg = "Instrument with FIGI [{}] is not present in open positions".format(self._figi)
3684
3685            for iType in TKS_INSTRUMENTS:
3686                for instrument in portfolio["stat"][iType]:
3687                    if instrument["figi"] == self._figi:
3688                        result = True
3689                        msg = "Instrument with FIGI [{}] is present in open positions".format(self._figi)
3690                        break
3691
3692        else:
3693            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3694
3695        uLogger.debug(msg)
3696
3697        return result
3698
3699    def GetInstrumentFromPortfolio(self, portfolio: dict = None) -> dict:
3700        """
3701        Returns instrument from the user's portfolio if it presents there.
3702        Instrument must be defined by `ticker` (highly priority) or `figi`.
3703
3704        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3705        :return: dict with instrument if portfolio contains open position with this instrument, `None` otherwise.
3706        """
3707        result = None
3708        msg = "Instrument not defined!"
3709
3710        if portfolio is None or not portfolio:
3711            portfolio = self.Overview(show=False)
3712
3713        if self._ticker:
3714            uLogger.debug("Searching instrument with ticker [{}] in opened positions...".format(self._ticker))
3715            msg = "Instrument with ticker [{}] is not present in open positions".format(self._ticker)
3716
3717            for iType in TKS_INSTRUMENTS:
3718                for instrument in portfolio["stat"][iType]:
3719                    if instrument["ticker"] == self._ticker:
3720                        result = instrument
3721                        msg = "Instrument with ticker [{}] and FIGI [{}] is present in open positions".format(self._ticker, instrument["figi"])
3722                        break
3723
3724        elif self._figi:
3725            uLogger.debug("Searching instrument with FIGI [{}] throwout opened positions...".format(self._figi))
3726            msg = "Instrument with FIGI [{}] is not present in open positions".format(self._figi)
3727
3728            for iType in TKS_INSTRUMENTS:
3729                for instrument in portfolio["stat"][iType]:
3730                    if instrument["figi"] == self._figi:
3731                        result = instrument
3732                        msg = "Instrument with ticker [{}] and FIGI [{}] is present in open positions".format(instrument["ticker"], self._figi)
3733                        break
3734
3735        else:
3736            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3737
3738        uLogger.debug(msg)
3739
3740        return result
3741
3742    def IsInLimitOrders(self, portfolio: dict = None) -> bool:
3743        """
3744        Checks if instrument is in the limit orders list. Instrument must be defined by `ticker` (highly priority) or `figi`.
3745
3746        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3747
3748        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3749        :return: `True` if limit orders list contains some limit orders for the instrument, `False` otherwise.
3750        """
3751        result = False
3752        msg = "Instrument not defined!"
3753
3754        if portfolio is None or not portfolio:
3755            portfolio = self.Overview(show=False)
3756
3757        if self._ticker:
3758            uLogger.debug("Searching instrument with ticker [{}] throw opened pending limit orders list...".format(self._ticker))
3759            msg = "Instrument with ticker [{}] is not present in opened pending limit orders list".format(self._ticker)
3760
3761            for instrument in portfolio["stat"]["orders"]:
3762                if instrument["ticker"] == self._ticker:
3763                    result = True
3764                    msg = "Instrument with ticker [{}] is present in limit orders list".format(self._ticker)
3765                    break
3766
3767        elif self._figi:
3768            uLogger.debug("Searching instrument with FIGI [{}] throw opened pending limit orders list...".format(self._figi))
3769            msg = "Instrument with FIGI [{}] is not present in opened pending limit orders list".format(self._figi)
3770
3771            for instrument in portfolio["stat"]["orders"]:
3772                if instrument["figi"] == self._figi:
3773                    result = True
3774                    msg = "Instrument with FIGI [{}] is present in opened pending limit orders list".format(self._figi)
3775                    break
3776
3777        else:
3778            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3779
3780        uLogger.debug(msg)
3781
3782        return result
3783
3784    def GetLimitOrderIDs(self, portfolio: dict = None) -> list[str]:
3785        """
3786        Returns list with all `orderID`s of opened pending limit orders for the instrument.
3787        Instrument must be defined by `ticker` (highly priority) or `figi`.
3788
3789        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3790
3791        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3792        :return: list with `orderID`s of limit orders.
3793        """
3794        result = []
3795        msg = "Instrument not defined!"
3796
3797        if portfolio is None or not portfolio:
3798            portfolio = self.Overview(show=False)
3799
3800        if self._ticker:
3801            uLogger.debug("Searching instrument with ticker [{}] throw opened pending limit orders list...".format(self._ticker))
3802            msg = "Instrument with ticker [{}] is not present in opened pending limit orders list".format(self._ticker)
3803
3804            for instrument in portfolio["stat"]["orders"]:
3805                if instrument["ticker"] == self._ticker:
3806                    result.append(instrument["orderID"])
3807
3808            if result:
3809                msg = "Instrument with ticker [{}] is present in limit orders list".format(self._ticker)
3810
3811        elif self._figi:
3812            uLogger.debug("Searching instrument with FIGI [{}] throw opened pending limit orders list...".format(self._figi))
3813            msg = "Instrument with FIGI [{}] is not present in opened pending limit orders list".format(self._figi)
3814
3815            for instrument in portfolio["stat"]["orders"]:
3816                if instrument["figi"] == self._figi:
3817                    result.append(instrument["orderID"])
3818
3819            if result:
3820                msg = "Instrument with FIGI [{}] is present in opened pending limit orders list".format(self._figi)
3821
3822        else:
3823            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3824
3825        uLogger.debug(msg)
3826
3827        return result
3828
3829    def IsInStopOrders(self, portfolio: dict = None) -> bool:
3830        """
3831        Checks if instrument is in the stop orders list. Instrument must be defined by `ticker` (highly priority) or `figi`.
3832
3833        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3834
3835        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3836        :return: `True` if stop orders list contains some stop orders for the instrument, `False` otherwise.
3837        """
3838        result = False
3839        msg = "Instrument not defined!"
3840
3841        if portfolio is None or not portfolio:
3842            portfolio = self.Overview(show=False)
3843
3844        if self._ticker:
3845            uLogger.debug("Searching instrument with ticker [{}] throw opened stop orders list...".format(self._ticker))
3846            msg = "Instrument with ticker [{}] is not present in opened stop orders list".format(self._ticker)
3847
3848            for instrument in portfolio["stat"]["stopOrders"]:
3849                if instrument["ticker"] == self._ticker:
3850                    result = True
3851                    msg = "Instrument with ticker [{}] is present in stop orders list".format(self._ticker)
3852                    break
3853
3854        elif self._figi:
3855            uLogger.debug("Searching instrument with FIGI [{}] throw opened stop orders list...".format(self._figi))
3856            msg = "Instrument with FIGI [{}] is not present in opened stop orders list".format(self._figi)
3857
3858            for instrument in portfolio["stat"]["stopOrders"]:
3859                if instrument["figi"] == self._figi:
3860                    result = True
3861                    msg = "Instrument with FIGI [{}] is present in opened stop orders list".format(self._figi)
3862                    break
3863
3864        else:
3865            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3866
3867        uLogger.debug(msg)
3868
3869        return result
3870
3871    def GetStopOrderIDs(self, portfolio: dict = None) -> list[str]:
3872        """
3873        Returns list with all `orderID`s of opened stop orders for the instrument.
3874        Instrument must be defined by `ticker` (highly priority) or `figi`.
3875
3876        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3877
3878        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3879        :return: list with `orderID`s of stop orders.
3880        """
3881        result = []
3882        msg = "Instrument not defined!"
3883
3884        if portfolio is None or not portfolio:
3885            portfolio = self.Overview(show=False)
3886
3887        if self._ticker:
3888            uLogger.debug("Searching instrument with ticker [{}] throw opened stop orders list...".format(self._ticker))
3889            msg = "Instrument with ticker [{}] is not present in opened stop orders list".format(self._ticker)
3890
3891            for instrument in portfolio["stat"]["stopOrders"]:
3892                if instrument["ticker"] == self._ticker:
3893                    result.append(instrument["orderID"])
3894
3895            if result:
3896                msg = "Instrument with ticker [{}] is present in stop orders list".format(self._ticker)
3897
3898        elif self._figi:
3899            uLogger.debug("Searching instrument with FIGI [{}] throw opened stop orders list...".format(self._figi))
3900            msg = "Instrument with FIGI [{}] is not present in opened stop orders list".format(self._figi)
3901
3902            for instrument in portfolio["stat"]["stopOrders"]:
3903                if instrument["figi"] == self._figi:
3904                    result.append(instrument["orderID"])
3905
3906            if result:
3907                msg = "Instrument with FIGI [{}] is present in opened stop orders list".format(self._figi)
3908
3909        else:
3910            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3911
3912        uLogger.debug(msg)
3913
3914        return result
3915
3916    def RequestLimits(self) -> dict:
3917        """
3918        Method for obtaining the available funds for withdrawal for current `accountId`.
3919
3920        See also:
3921        - REST API for limits: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetWithdrawLimits
3922        - `OverviewLimits()` method
3923
3924        :return: dict with raw data from server that contains free funds for withdrawal. Example of dict:
3925                 `{"money": [{"currency": "rub", "units": "100", "nano": 290000000}, {...}], "blocked": [...], "blockedGuarantee": [...]}`.
3926                 Here `money` is an array of portfolio currency positions, `blocked` is an array of blocked currency
3927                 positions of the portfolio and `blockedGuarantee` is locked money under collateral for futures.
3928        """
3929        if self.accountId is None or not self.accountId:
3930            uLogger.error("Variable `accountId` must be defined for using this method!")
3931            raise Exception("Account ID required")
3932
3933        uLogger.debug("Requesting current available funds for withdrawal. Wait, please...")
3934
3935        self.body = str({"accountId": self.accountId})
3936        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetWithdrawLimits"
3937        rawLimits = self.SendAPIRequest(portfolioURL, reqType="POST")
3938
3939        if self.moreDebug:
3940            uLogger.debug("Records about available funds for withdrawal successfully received")
3941
3942        return rawLimits
3943
3944    def OverviewLimits(self, show: bool = False, onlyFiles=False) -> dict:
3945        """
3946        Method for parsing and show table with available funds for withdrawal for current `accountId`.
3947
3948        See also: `RequestLimits()`.
3949
3950        :param show: if `False` then only dictionary returns, if `True` then also print withdrawal limits to log.
3951        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
3952        :return: dict with raw parsed data from server and some calculated statistics about it.
3953        """
3954        if self.accountId is None or not self.accountId:
3955            uLogger.error("Variable `accountId` must be defined for using this method!")
3956            raise Exception("Account ID required")
3957
3958        rawLimits = self.RequestLimits()  # raw response with current available funds for withdrawal
3959
3960        view = {
3961            "rawLimits": rawLimits,
3962            "limits": {  # parsed data for every currency:
3963                "money": {  # this is an array of portfolio currency positions
3964                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["money"]
3965                },
3966                "blocked": {  # this is an array of blocked currency
3967                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["blocked"]
3968                },
3969                "blockedGuarantee": {  # this is locked money under collateral for futures
3970                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["blockedGuarantee"]
3971                },
3972            },
3973        }
3974
3975        # --- Prepare text table with limits in human-readable format:
3976        if show or onlyFiles:
3977            info = [
3978                "# Withdrawal limits\n\n",
3979                "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
3980                "* **Account ID:** [{}]\n".format(self.accountId),
3981            ]
3982
3983            if view["limits"]["money"]:
3984                info.extend([
3985                    "\n| Currencies | Total         | Available for withdrawal | Blocked for trade | Futures guarantee |\n",
3986                    "|------------|---------------|--------------------------|-------------------|-------------------|\n",
3987                ])
3988
3989            else:
3990                info.append("\nNo withdrawal limits\n")
3991
3992            for curr in view["limits"]["money"].keys():
3993                blocked = view["limits"]["blocked"][curr] if curr in view["limits"]["blocked"].keys() else 0
3994                blockedGuarantee = view["limits"]["blockedGuarantee"][curr] if curr in view["limits"]["blockedGuarantee"].keys() else 0
3995                availableMoney = view["limits"]["money"][curr] - (blocked + blockedGuarantee)
3996
3997                infoStr = "| {:<10} | {:<13} | {:<24} | {:<17} | {:<17} |\n".format(
3998                    "[{}]".format(curr),
3999                    "{:.2f}".format(view["limits"]["money"][curr]),
4000                    "{:.2f}".format(availableMoney),
4001                    "{:.2f}".format(view["limits"]["blocked"][curr]) if curr in view["limits"]["blocked"].keys() else "—",
4002                    "{:.2f}".format(view["limits"]["blockedGuarantee"][curr]) if curr in view["limits"]["blockedGuarantee"].keys() else "—",
4003                )
4004
4005                if curr == "rub":
4006                    info.insert(5, infoStr)  # hack: insert "rub" at the first position in table and after headers
4007
4008                else:
4009                    info.append(infoStr)
4010
4011            infoText = "".join(info)
4012
4013            if show and not onlyFiles:
4014                uLogger.info(infoText)
4015
4016            if self.withdrawalLimitsFile and (show or onlyFiles):
4017                with open(self.withdrawalLimitsFile, "w", encoding="UTF-8") as fH:
4018                    fH.write(infoText)
4019
4020                uLogger.info("Client's withdrawal limits was saved to file: [{}]".format(os.path.abspath(self.withdrawalLimitsFile)))
4021
4022                if self.useHTMLReports:
4023                    htmlFilePath = self.withdrawalLimitsFile.replace(".md", ".html") if self.withdrawalLimitsFile.endswith(".md") else self.withdrawalLimitsFile + ".html"
4024                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
4025                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Withdrawal limits", commonCSS=COMMON_CSS, markdown=infoText))
4026
4027                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
4028
4029        return view
4030
4031    def RequestAccounts(self) -> dict:
4032        """
4033        Method for requesting all brokerage accounts (`accountId`s) of current user detected by `token`.
4034
4035        See also:
4036        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetAccounts
4037        - What does account fields mean: https://tinkoff.github.io/investAPI/users/#account
4038        - `OverviewUserInfo()` method
4039
4040        :return: dict with raw data from server that contains accounts info. Example of dict:
4041                 `{"accounts": [{"id": "20000xxxxx", "type": "ACCOUNT_TYPE_TINKOFF", "name": "TKSBrokerAPI account",
4042                   "status": "ACCOUNT_STATUS_OPEN", "openedDate": "2018-05-23T00:00:00Z",
4043                   "closedDate": "1970-01-01T00:00:00Z", "accessLevel": "ACCOUNT_ACCESS_LEVEL_FULL_ACCESS"}, ...]}`.
4044                 If `closedDate="1970-01-01T00:00:00Z"` it means that account is active now.
4045        """
4046        uLogger.debug("Requesting all brokerage accounts of current user detected by its token. Wait, please...")
4047
4048        self.body = str({})
4049        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetAccounts"
4050        rawAccounts = self.SendAPIRequest(portfolioURL, reqType="POST")
4051
4052        if self.moreDebug:
4053            uLogger.debug("Records about available accounts successfully received")
4054
4055        return rawAccounts
4056
4057    def RequestUserInfo(self) -> dict:
4058        """
4059        Method for requesting common user's information.
4060
4061        See also:
4062        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetInfo
4063        - What does user info fields mean: https://tinkoff.github.io/investAPI/users/#getinforequest
4064        - What does `qualified_for_work_with` field mean: https://tinkoff.github.io/investAPI/faq_users/#qualified_for_work_with
4065        - `OverviewUserInfo()` method
4066
4067        :return: dict with raw data from server that contains user's information. Example of dict:
4068                 `{"premStatus": true, "qualStatus": false, "qualifiedForWorkWith": ["bond", "foreign_shares", "leverage",
4069                   "russian_shares", "structured_income_bonds"], "tariff": "premium"}`.
4070        """
4071        uLogger.debug("Requesting common user's information. Wait, please...")
4072
4073        self.body = str({})
4074        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetInfo"
4075        rawUserInfo = self.SendAPIRequest(portfolioURL, reqType="POST")
4076
4077        if self.moreDebug:
4078            uLogger.debug("Records about current user successfully received")
4079
4080        return rawUserInfo
4081
4082    def RequestMarginStatus(self, accountId: str = None) -> dict:
4083        """
4084        Method for requesting margin calculation for defined account ID.
4085
4086        See also:
4087        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetMarginAttributes
4088        - What does margin fields mean: https://tinkoff.github.io/investAPI/users/#getmarginattributesresponse
4089        - `OverviewUserInfo()` method
4090
4091        :param accountId: string with numeric account ID. If `None`, then used class field `accountId`.
4092        :return: dict with raw data from server that contains margin calculation. If margin is disabled then returns empty dict.
4093                 Example of responses:
4094                 status code 400: `{"code": 3, "message": "account margin status is disabled", "description": "30051" }`, returns: `{}`.
4095                 status code 200: `{"liquidPortfolio": {"currency": "rub", "units": "7175", "nano": 560000000},
4096                                    "startingMargin": {"currency": "rub", "units": "6311", "nano": 840000000},
4097                                    "minimalMargin": {"currency": "rub", "units": "3155", "nano": 920000000},
4098                                    "fundsSufficiencyLevel": {"units": "1", "nano": 280000000},
4099                                    "amountOfMissingFunds": {"currency": "rub", "units": "-863", "nano": -720000000}}`.
4100        """
4101        if accountId is None or not accountId:
4102            if self.accountId is None or not self.accountId:
4103                uLogger.error("Variable `accountId` must be defined for using this method!")
4104                raise Exception("Account ID required")
4105
4106            else:
4107                accountId = self.accountId  # use `self.accountId` (main ID) by default
4108
4109        uLogger.debug("Requesting margin calculation for accountId [{}]. Wait, please...".format(accountId))
4110
4111        self.body = str({"accountId": accountId})
4112        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetMarginAttributes"
4113        rawMargin = self.SendAPIRequest(portfolioURL, reqType="POST")
4114
4115        if rawMargin == {"code": 3, "message": "account margin status is disabled", "description": "30051"}:
4116            uLogger.debug("Server response: margin status is disabled for current accountId [{}]".format(accountId))
4117            rawMargin = {}
4118
4119        else:
4120            if self.moreDebug:
4121                uLogger.debug("Records with margin calculation for accountId [{}] successfully received".format(accountId))
4122
4123        return rawMargin
4124
4125    def RequestTariffLimits(self) -> dict:
4126        """
4127        Method for requesting limits of current tariff (connections, API methods etc.) of current user detected by `token`.
4128
4129        See also:
4130        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetUserTariff
4131        - What does fields in tariff mean: https://tinkoff.github.io/investAPI/users/#getusertariffrequest
4132        - Unary limit: https://tinkoff.github.io/investAPI/users/#unarylimit
4133        - Stream limit: https://tinkoff.github.io/investAPI/users/#streamlimit
4134        - `OverviewUserInfo()` method
4135
4136        :return: dict with raw data from server that contains limits of current tariff. Example of dict:
4137                 `{"unaryLimits": [{"limitPerMinute": 0, "methods": ["methods", "methods"]}, ...],
4138                   "streamLimits": [{"streams": ["streams", "streams"], "limit": 6}, ...]}`.
4139        """
4140        uLogger.debug("Requesting limits of current tariff. Wait, please...")
4141
4142        self.body = str({})
4143        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetUserTariff"
4144        rawTariffLimits = self.SendAPIRequest(portfolioURL, reqType="POST")
4145
4146        if self.moreDebug:
4147            uLogger.debug("Records with limits of current tariff successfully received")
4148
4149        return rawTariffLimits
4150
4151    def RequestBondCoupons(self, iJSON: dict) -> dict:
4152        """
4153        Requesting bond payment calendar from official placement date to maturity date. If these dates are unknown
4154        then requesting dates `"from": "1970-01-01T00:00:00.000Z"` and `"to": "2099-12-31T23:59:59.000Z"`.
4155        All dates are in UTC timezone.
4156
4157        REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_GetBondCoupons
4158        Documentation:
4159        - request: https://tinkoff.github.io/investAPI/instruments/#getbondcouponsrequest
4160        - response: https://tinkoff.github.io/investAPI/instruments/#coupon
4161
4162        See also: `ExtendBondsData()`.
4163
4164        :param iJSON: raw json data of a bond from broker server, example `iJSON = self.iList["Bonds"][self._ticker]`
4165                      If raw iJSON is not data of bond then server returns an error [400] with message:
4166                      `{"code": 3, "message": "instrument type is not bond", "description": "30048"}`.
4167        :return: dictionary with bond payment calendar. Response example
4168                 `{"events": [{"figi": "TCS00A101YV8", "couponDate": "2023-07-26T00:00:00Z", "couponNumber": "12",
4169                   "fixDate": "2023-07-25T00:00:00Z", "payOneBond": {"currency": "rub", "units": "7", "nano": 170000000},
4170                   "couponType": "COUPON_TYPE_CONSTANT", "couponStartDate": "2023-04-26T00:00:00Z",
4171                   "couponEndDate": "2023-07-26T00:00:00Z", "couponPeriod": 91}, {...}, ...]}`
4172        """
4173        if iJSON["figi"] is None or not iJSON["figi"]:
4174            uLogger.error("FIGI must be defined for using this method!")
4175            raise Exception("FIGI required")
4176
4177        startDate = iJSON["placementDate"] if "placementDate" in iJSON.keys() else "1970-01-01T00:00:00.000Z"
4178        endDate = iJSON["maturityDate"] if "maturityDate" in iJSON.keys() else "2099-12-31T23:59:59.000Z"
4179
4180        uLogger.debug("Requesting bond payment calendar, {}FIGI: [{}], from: [{}], to: [{}]. Wait, please...".format(
4181            "ticker: [{}], ".format(iJSON["ticker"]) if "ticker" in iJSON.keys() else "",
4182            self._figi,
4183            startDate,
4184            endDate,
4185        ))
4186
4187        self.body = str({"figi": iJSON["figi"], "from": startDate, "to": endDate})
4188        calendarURL = self.server + r"/tinkoff.public.invest.api.contract.v1.InstrumentsService/GetBondCoupons"
4189        calendar = self.SendAPIRequest(calendarURL, reqType="POST")
4190
4191        if calendar == {"code": 3, "message": "instrument type is not bond", "description": "30048"}:
4192            uLogger.warning("Instrument type is not bond!")
4193
4194        else:
4195            if self.moreDebug:
4196                uLogger.debug("Records about bond payment calendar successfully received")
4197
4198        return calendar
4199
4200    def ExtendBondsData(self, instruments: list[str], xlsx: bool = False) -> pd.DataFrame:
4201        """
4202        Requests jsons with raw bonds data for every ticker or FIGI in instruments list and transform it to the wider
4203        Pandas DataFrame with more information about bonds: main info, current prices, bond payment calendar,
4204        coupon yields, current yields and some statistics etc.
4205
4206        WARNING! This is too long operation if a lot of bonds requested from broker server.
4207
4208        See also: `ShowInstrumentInfo()`, `CreateBondsCalendar()`, `ShowBondsCalendar()`, `RequestBondCoupons()`.
4209
4210        :param instruments: list of strings with tickers or FIGIs.
4211        :param xlsx: if True then also exports Pandas DataFrame to xlsx-file `bondsXLSXFile`, default `ext-bonds.xlsx`,
4212                     for further used by data scientists or stock analytics.
4213        :return: wider Pandas DataFrame with more full and calculated data about bonds, than raw response from broker.
4214                 In XLSX-file and Pandas DataFrame fields mean:
4215                 - main info about bond: https://tinkoff.github.io/investAPI/instruments/#bond
4216                 - info about coupon: https://tinkoff.github.io/investAPI/instruments/#coupon
4217        """
4218        if instruments is None or not instruments:
4219            uLogger.error("List of tickers or FIGIs must be defined for using this method!")
4220            raise Exception("Ticker or FIGI required")
4221
4222        if isinstance(instruments, str):
4223            instruments = [instruments]
4224
4225        uniqueInstruments = self.GetUniqueFIGIs(instruments)
4226
4227        uLogger.debug("Requesting raw bonds calendar from server, transforming and extending it. Wait, please...")
4228
4229        iCount = len(uniqueInstruments)
4230        tooLong = iCount >= 20
4231        if tooLong:
4232            uLogger.warning("You requested a lot of bonds! Operation will takes more time. Wait, please...")
4233
4234        bonds = None
4235        for i, self._figi in enumerate(uniqueInstruments):
4236            instrument = self.SearchByFIGI(requestPrice=False)  # raw data about instrument from server
4237
4238            if "type" in instrument.keys() and instrument["type"] == "Bonds":
4239                # raw bond data from server where fields mean: https://tinkoff.github.io/investAPI/instruments/#bond
4240                rawBond = self.SearchByFIGI(requestPrice=True)
4241
4242                # Widen raw data with UTC current time (iData["actualDateTime"]):
4243                actualDate = datetime.now(tzutc())
4244                iData = {"actualDateTime": actualDate.strftime(TKS_DATE_TIME_FORMAT)} | rawBond
4245
4246                # Widen raw data with bond payment calendar (iData["rawCalendar"]):
4247                iData = iData | {"rawCalendar": self.RequestBondCoupons(iJSON=iData)}
4248
4249                # Replace some values with human-readable:
4250                iData["nominalCurrency"] = iData["nominal"]["currency"]
4251                iData["nominal"] = NanoToFloat(iData["nominal"]["units"], iData["nominal"]["nano"])
4252                iData["placementPrice"] = NanoToFloat(iData["placementPrice"]["units"], iData["placementPrice"]["nano"])
4253                iData["aciCurrency"] = iData["aciValue"]["currency"]
4254                iData["aciValue"] = NanoToFloat(iData["aciValue"]["units"], iData["aciValue"]["nano"])
4255                iData["issueSize"] = int(iData["issueSize"])
4256                iData["issueSizePlan"] = int(iData["issueSizePlan"])
4257                iData["tradingStatus"] = TKS_TRADING_STATUSES[iData["tradingStatus"]]
4258                iData["step"] = iData["step"] if "step" in iData.keys() else 0
4259                iData["realExchange"] = TKS_REAL_EXCHANGES[iData["realExchange"]]
4260                iData["klong"] = NanoToFloat(iData["klong"]["units"], iData["klong"]["nano"]) if "klong" in iData.keys() else 0
4261                iData["kshort"] = NanoToFloat(iData["kshort"]["units"], iData["kshort"]["nano"]) if "kshort" in iData.keys() else 0
4262                iData["dlong"] = NanoToFloat(iData["dlong"]["units"], iData["dlong"]["nano"]) if "dlong" in iData.keys() else 0
4263                iData["dshort"] = NanoToFloat(iData["dshort"]["units"], iData["dshort"]["nano"]) if "dshort" in iData.keys() else 0
4264                iData["dlongMin"] = NanoToFloat(iData["dlongMin"]["units"], iData["dlongMin"]["nano"]) if "dlongMin" in iData.keys() else 0
4265                iData["dshortMin"] = NanoToFloat(iData["dshortMin"]["units"], iData["dshortMin"]["nano"]) if "dshortMin" in iData.keys() else 0
4266
4267                # Widen raw data with price fields from `currentPrice` values (all prices are actual at `actualDateTime` date):
4268                iData["limitUpPercent"] = iData["currentPrice"]["limitUp"]  # max price on current day in percents of nominal
4269                iData["limitDownPercent"] = iData["currentPrice"]["limitDown"]  # min price on current day in percents of nominal
4270                iData["lastPricePercent"] = iData["currentPrice"]["lastPrice"]  # last price on market in percents of nominal
4271                iData["closePricePercent"] = iData["currentPrice"]["closePrice"]  # previous day close in percents of nominal
4272                iData["changes"] = iData["currentPrice"]["changes"]  # this is percent of changes between `currentPrice` and `lastPrice`
4273                iData["limitUp"] = iData["limitUpPercent"] * iData["nominal"] / 100  # max price on current day is `limitUpPercent` * `nominal`
4274                iData["limitDown"] = iData["limitDownPercent"] * iData["nominal"] / 100  # min price on current day is `limitDownPercent` * `nominal`
4275                iData["lastPrice"] = iData["lastPricePercent"] * iData["nominal"] / 100  # last price on market is `lastPricePercent` * `nominal`
4276                iData["closePrice"] = iData["closePricePercent"] * iData["nominal"] / 100  # previous day close is `closePricePercent` * `nominal`
4277                iData["changesDelta"] = iData["lastPrice"] - iData["closePrice"]  # this is delta between last deal price and last close
4278
4279                # Widen raw data with calendar data from `rawCalendar` values:
4280                calendarData = []
4281                if "events" in iData["rawCalendar"].keys():
4282                    for item in iData["rawCalendar"]["events"]:
4283                        calendarData.append({
4284                            "couponDate": item["couponDate"],
4285                            "couponNumber": int(item["couponNumber"]),
4286                            "fixDate": item["fixDate"] if "fixDate" in item.keys() else "",
4287                            "payCurrency": item["payOneBond"]["currency"],
4288                            "payOneBond": NanoToFloat(item["payOneBond"]["units"], item["payOneBond"]["nano"]),
4289                            "couponType": TKS_COUPON_TYPES[item["couponType"]],
4290                            "couponStartDate": item["couponStartDate"],
4291                            "couponEndDate": item["couponEndDate"],
4292                            "couponPeriod": item["couponPeriod"],
4293                        })
4294
4295                    # if maturity date is unknown then uses the latest date in bond payment calendar for it:
4296                    if "maturityDate" not in iData.keys():
4297                        iData["maturityDate"] = datetime.strptime(calendarData[0]["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_DATE_TIME_FORMAT) if calendarData else ""
4298
4299                # Widen raw data with Coupon Rate.
4300                # This is sum of all coupon payments divided on nominal price and expire days sum and then multiple on 365 days and 100%:
4301                iData["sumCoupons"] = sum([coupon["payOneBond"] for coupon in calendarData])
4302                iData["periodDays"] = sum([coupon["couponPeriod"] for coupon in calendarData])
4303                iData["couponsYield"] = 100 * 365 * (iData["sumCoupons"] / iData["nominal"]) / iData["periodDays"] if iData["nominal"] != 0 and iData["periodDays"] != 0 else 0.
4304
4305                # Widen raw data with Yield to Maturity (YTM) on current date.
4306                # This is sum of all stayed coupons to maturity minus ACI and divided on current bond price and then multiple on stayed days and 100%:
4307                maturityDate = datetime.strptime(iData["maturityDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()) if iData["maturityDate"] else None
4308                iData["daysToMaturity"] = (maturityDate - actualDate).days if iData["maturityDate"] else None
4309                iData["sumLastCoupons"] = sum([coupon["payOneBond"] for coupon in calendarData if datetime.strptime(coupon["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()) > actualDate])
4310                iData["lastPayments"] = iData["sumLastCoupons"] - iData["aciValue"]  # sum of all last coupons minus current ACI value
4311                iData["currentYield"] = 100 * 365 * (iData["lastPayments"] / iData["lastPrice"]) / iData["daysToMaturity"] if iData["lastPrice"] != 0 and iData["daysToMaturity"] != 0 else 0.
4312
4313                iData["calendar"] = calendarData  # adds calendar at the end
4314
4315                # Remove not used data:
4316                iData.pop("uid")
4317                iData.pop("positionUid")
4318                iData.pop("currentPrice")
4319                iData.pop("rawCalendar")
4320
4321                colNames = list(iData.keys())
4322                if bonds is None:
4323                    bonds = pd.DataFrame(data=pd.DataFrame.from_records(data=[iData], columns=colNames))
4324
4325                else:
4326                    bonds = pd.concat([bonds, pd.DataFrame.from_records(data=[iData], columns=colNames)], axis=0, ignore_index=True)
4327
4328            else:
4329                uLogger.warning("Instrument is not a bond!")
4330
4331            processed = round(100 * (i + 1) / iCount, 1)
4332            if tooLong and processed % 5 == 0:
4333                uLogger.info("{}% processed [{} / {}]...".format(round(processed), i + 1, iCount))
4334
4335            else:
4336                uLogger.debug("{}% bonds processed [{} / {}]...".format(processed, i + 1, iCount))
4337
4338        bonds.index = bonds["ticker"].tolist()  # replace indexes with ticker names
4339
4340        # Saving bonds from Pandas DataFrame to XLSX sheet:
4341        if xlsx and self.bondsXLSXFile:
4342            with pd.ExcelWriter(
4343                    path=self.bondsXLSXFile,
4344                    date_format=TKS_DATE_FORMAT,
4345                    datetime_format=TKS_DATE_TIME_FORMAT,
4346                    mode="w",
4347            ) as writer:
4348                bonds.to_excel(
4349                    writer,
4350                    sheet_name="Extended bonds data",
4351                    index=True,
4352                    encoding="UTF-8",
4353                    freeze_panes=(1, 1),
4354                )  # saving as XLSX-file with freeze first row and column as headers
4355
4356            uLogger.info("XLSX-file with extended bonds data for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(self.bondsXLSXFile)))
4357
4358        return bonds
4359
4360    def CreateBondsCalendar(self, extBonds: pd.DataFrame, xlsx: bool = False) -> pd.DataFrame:
4361        """
4362        Creates bond payments calendar as Pandas DataFrame, and also save it to the XLSX-file, `calendar.xlsx` by default.
4363
4364        WARNING! This is too long operation if a lot of bonds requested from broker server.
4365
4366        See also: `ShowBondsCalendar()`, `ExtendBondsData()`.
4367
4368        :param extBonds: Pandas DataFrame object returns by `ExtendBondsData()` method and contains
4369                        extended information about bonds: main info, current prices, bond payment calendar,
4370                        coupon yields, current yields and some statistics etc.
4371                        If this parameter is `None` then used `figi` or `ticker` as bond name and then calculate `ExtendBondsData()`.
4372        :param xlsx: if True then also exports Pandas DataFrame to file `calendarFile` + `".xlsx"`, `calendar.xlsx` by default,
4373                     for further used by data scientists or stock analytics.
4374        :return: Pandas DataFrame with only bond payments calendar data. Fields mean: https://tinkoff.github.io/investAPI/instruments/#coupon
4375        """
4376        if extBonds is None or not isinstance(extBonds, pd.DataFrame) or extBonds.empty:
4377            extBonds = self.ExtendBondsData(instruments=[self._figi, self._ticker], xlsx=False)
4378
4379        uLogger.debug("Generating bond payments calendar data. Wait, please...")
4380
4381        colNames = ["Paid", "Payment date", "FIGI", "Ticker", "Name", "No.", "Value", "Currency", "Coupon type", "Period", "End registry date", "Coupon start date", "Coupon end date"]
4382        colID = ["paid", "couponDate", "figi", "ticker", "name", "couponNumber", "payOneBond", "payCurrency", "couponType", "couponPeriod", "fixDate", "couponStartDate", "couponEndDate"]
4383        calendar = None
4384        for bond in extBonds.iterrows():
4385            for item in bond[1]["calendar"]:
4386                cData = {
4387                    "paid": datetime.now(tzutc()) > datetime.strptime(item["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()),
4388                    "couponDate": item["couponDate"],
4389                    "figi": bond[1]["figi"],
4390                    "ticker": bond[1]["ticker"],
4391                    "name": bond[1]["name"],
4392                    "couponNumber": item["couponNumber"],
4393                    "payOneBond": item["payOneBond"],
4394                    "payCurrency": item["payCurrency"],
4395                    "couponType": item["couponType"],
4396                    "couponPeriod": item["couponPeriod"],
4397                    "fixDate": item["fixDate"],
4398                    "couponStartDate": item["couponStartDate"],
4399                    "couponEndDate": item["couponEndDate"],
4400                }
4401
4402                if calendar is None:
4403                    calendar = pd.DataFrame(data=pd.DataFrame.from_records(data=[cData], columns=colID))
4404
4405                else:
4406                    calendar = pd.concat([calendar, pd.DataFrame.from_records(data=[cData], columns=colID)], axis=0, ignore_index=True)
4407
4408        if calendar is not None:
4409            calendar = calendar.sort_values(by=["couponDate"], axis=0, ascending=True)  # sort all payments for all bonds by payment date
4410
4411            # Saving calendar from Pandas DataFrame to XLSX sheet:
4412            if xlsx:
4413                xlsxCalendarFile = self.calendarFile.replace(".md", ".xlsx") if self.calendarFile.endswith(".md") else self.calendarFile + ".xlsx"
4414
4415                with pd.ExcelWriter(
4416                        path=xlsxCalendarFile,
4417                        date_format=TKS_DATE_FORMAT,
4418                        datetime_format=TKS_DATE_TIME_FORMAT,
4419                        mode="w",
4420                ) as writer:
4421                    humanReadable = calendar.copy(deep=True)
4422                    humanReadable["couponDate"] = humanReadable["couponDate"].apply(lambda x: x.split("T")[0])
4423                    humanReadable["fixDate"] = humanReadable["fixDate"].apply(lambda x: x.split("T")[0])
4424                    humanReadable["couponStartDate"] = humanReadable["couponStartDate"].apply(lambda x: x.split("T")[0])
4425                    humanReadable["couponEndDate"] = humanReadable["couponEndDate"].apply(lambda x: x.split("T")[0])
4426                    humanReadable.columns = colNames  # human-readable column names
4427
4428                    humanReadable.to_excel(
4429                        writer,
4430                        sheet_name="Bond payments calendar",
4431                        index=False,
4432                        encoding="UTF-8",
4433                        freeze_panes=(1, 2),
4434                    )  # saving as XLSX-file with freeze first row and column as headers
4435
4436                    del humanReadable  # release df in memory
4437
4438                uLogger.info("XLSX-file with bond payments calendar for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(xlsxCalendarFile)))
4439
4440        return calendar
4441
4442    def ShowBondsCalendar(self, extBonds: pd.DataFrame, show: bool = True, onlyFiles=False) -> str:
4443        """
4444        Show bond payments calendar as a table. One row in input `bonds` dataframe contains one bond.
4445        Also, creates Markdown file with calendar data, `calendar.md` by default.
4446
4447        See also: `ShowInstrumentInfo()`, `RequestBondCoupons()`, `CreateBondsCalendar()` and `ExtendBondsData()`.
4448
4449        :param extBonds: Pandas DataFrame object returns by `ExtendBondsData()` method and contains
4450                        extended information about bonds: main info, current prices, bond payment calendar,
4451                        coupon yields, current yields and some statistics etc.
4452                        If this parameter is `None` then used `figi` or `ticker` as bond name and then calculate `ExtendBondsData()`.
4453        :param show: if `True` then also printing bonds payment calendar to the console,
4454                     otherwise save to file `calendarFile` only. `False` by default.
4455        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
4456        :return: multilines text in Markdown format with bonds payment calendar as a table.
4457        """
4458        if extBonds is None or not isinstance(extBonds, pd.DataFrame) or extBonds.empty:
4459            extBonds = self.ExtendBondsData(instruments=[self._figi, self._ticker], xlsx=show or onlyFiles)
4460
4461        infoText = "# Bond payments calendar\n\n"
4462
4463        calendar = self.CreateBondsCalendar(extBonds, xlsx=show or onlyFiles)  # generate Pandas DataFrame with full calendar data
4464
4465        if not (calendar is None or calendar.empty):
4466            splitLine = "|       |                 |              |              |     |               |           |        |                   |\n"
4467
4468            info = [
4469                "* **Actual on date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4470                "| Paid  | Payment date    | FIGI         | Ticker       | No. | Value         | Type      | Period | End registry date |\n",
4471                "|-------|-----------------|--------------|--------------|-----|---------------|-----------|--------|-------------------|\n",
4472            ]
4473
4474            newMonth = False
4475            notOneBond = calendar["figi"].nunique() > 1
4476            for i, bond in enumerate(calendar.iterrows()):
4477                if newMonth and notOneBond:
4478                    info.append(splitLine)
4479
4480                info.append(
4481                    "| {:<5} | {:<15} | {:<12} | {:<12} | {:<3} | {:<13} | {:<9} | {:<6} | {:<17} |\n".format(
4482                        "  √" if bond[1]["paid"] else "  —",
4483                        bond[1]["couponDate"].split("T")[0],
4484                        bond[1]["figi"],
4485                        bond[1]["ticker"],
4486                        bond[1]["couponNumber"],
4487                        "{} {}".format(
4488                            "{}".format(round(bond[1]["payOneBond"], 6)).rstrip("0").rstrip("."),
4489                            bond[1]["payCurrency"],
4490                        ),
4491                        bond[1]["couponType"],
4492                        bond[1]["couponPeriod"],
4493                        bond[1]["fixDate"].split("T")[0],
4494                    )
4495                )
4496
4497                if i < len(calendar.values) - 1:
4498                    curDate = datetime.strptime(bond[1]["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc())
4499                    nextDate = datetime.strptime(calendar["couponDate"].values[i + 1], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc())
4500                    newMonth = False if curDate.month == nextDate.month else True
4501
4502                else:
4503                    newMonth = False
4504
4505            infoText += "".join(info)
4506
4507            if show and not onlyFiles:
4508                uLogger.info("{}".format(infoText))
4509
4510            if self.calendarFile is not None and (show or onlyFiles):
4511                with open(self.calendarFile, "w", encoding="UTF-8") as fH:
4512                    fH.write(infoText)
4513
4514                uLogger.info("Bond payments calendar was saved to file: [{}]".format(os.path.abspath(self.calendarFile)))
4515
4516                if self.useHTMLReports:
4517                    htmlFilePath = self.calendarFile.replace(".md", ".html") if self.calendarFile.endswith(".md") else self.calendarFile + ".html"
4518                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
4519                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Bond payments calendar", commonCSS=COMMON_CSS, markdown=infoText))
4520
4521                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
4522
4523        else:
4524            infoText += "No data\n"
4525
4526        return infoText
4527
4528    def OverviewAccounts(self, show: bool = False, onlyFiles=False) -> dict:
4529        """
4530        Method for parsing and show simple table with all available user accounts.
4531
4532        See also: `RequestAccounts()` and `OverviewUserInfo()` methods.
4533
4534        :param show: if `False` then only dictionary with accounts data returns, if `True` then also print it to log.
4535        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
4536        :return: dict with parsed accounts data received from `RequestAccounts()` method. Example of dict:
4537                 `view = {"rawAccounts": {rawAccounts from RequestAccounts() method...},
4538                          "stat": {"accountId string": {"type": "Tinkoff brokerage account", "name": "Test - 1",
4539                                                        "status": "Opened and active account", "opened": "2018-05-23 00:00:00",
4540                                                        "closed": "—", "access": "Full access" }, ...}}`
4541        """
4542        rawAccounts = self.RequestAccounts()  # Raw responses with accounts
4543
4544        # This is an array of dict with user accounts, its `accountId`s and some parsed data:
4545        accounts = {
4546            item["id"]: {
4547                "type": TKS_ACCOUNT_TYPES[item["type"]],
4548                "name": item["name"],
4549                "status": TKS_ACCOUNT_STATUSES[item["status"]],
4550                "opened": datetime.strptime(item["openedDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4551                "closed": datetime.strptime(item["closedDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT) if item["closedDate"] != "1970-01-01T00:00:00Z" else "—",
4552                "access": TKS_ACCESS_LEVELS[item["accessLevel"]],
4553            } for item in rawAccounts["accounts"]
4554        }
4555
4556        # Raw and parsed data with some fields replaced in "stat" section:
4557        view = {
4558            "rawAccounts": rawAccounts,
4559            "stat": accounts,
4560        }
4561
4562        # --- Prepare simple text table with only accounts data in human-readable format:
4563        if show or onlyFiles:
4564            info = [
4565                "# User accounts\n\n",
4566                "* **Actual date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4567                "| Account ID   | Type                      | Status                    | Name                           |\n",
4568                "|--------------|---------------------------|---------------------------|--------------------------------|\n",
4569            ]
4570
4571            for account in view["stat"].keys():
4572                info.extend([
4573                    "| {:<12} | {:<25} | {:<25} | {:<30} |\n".format(
4574                        account,
4575                        view["stat"][account]["type"],
4576                        view["stat"][account]["status"],
4577                        view["stat"][account]["name"],
4578                    )
4579                ])
4580
4581            infoText = "".join(info)
4582
4583            if show and not onlyFiles:
4584                uLogger.info(infoText)
4585
4586            if self.userAccountsFile and (show or onlyFiles):
4587                with open(self.userAccountsFile, "w", encoding="UTF-8") as fH:
4588                    fH.write(infoText)
4589
4590                uLogger.info("User accounts were saved to file: [{}]".format(os.path.abspath(self.userAccountsFile)))
4591
4592                if self.useHTMLReports:
4593                    htmlFilePath = self.userAccountsFile.replace(".md", ".html") if self.userAccountsFile.endswith(".md") else self.userAccountsFile + ".html"
4594                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
4595                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="User accounts", commonCSS=COMMON_CSS, markdown=infoText))
4596
4597                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
4598
4599        return view
4600
4601    def OverviewUserInfo(self, show: bool = False, onlyFiles=False) -> dict:
4602        """
4603        Method for parsing and show all available user's data (`accountId`s, common user information, margin status and tariff connections limit).
4604
4605        See also: `OverviewAccounts()`, `RequestAccounts()`, `RequestUserInfo()`, `RequestMarginStatus()` and `RequestTariffLimits()` methods.
4606
4607        :param show: if `False` then only dictionary returns, if `True` then also print user's data to log.
4608        :param onlyFiles: if `True` then do not show Markdown table in the console, but only generates report files.
4609        :return: dict with raw parsed data from server and some calculated statistics about it.
4610        """
4611        overview = self.Overview(show=False)  # Request current user portfolio for the ability to calculate missing funds
4612        tmpTicker = self._ticker
4613        self._ticker = "RUB000UTSTOM"  # This instrument show in rub how much money cost current margin
4614        missing = self.GetInstrumentFromPortfolio(portfolio=overview)
4615        self._ticker = tmpTicker
4616
4617        rawUserInfo = self.RequestUserInfo()  # Raw response with common user info
4618        overviewAccount = self.OverviewAccounts(show=False)  # Raw and parsed accounts data
4619        rawAccounts = overviewAccount["rawAccounts"]  # Raw response with user accounts data
4620        accounts = overviewAccount["stat"]  # Dict with only statistics about user accounts
4621        rawMargins = {account: self.RequestMarginStatus(accountId=account) for account in accounts.keys()}  # Raw response with margin calculation for every account ID
4622        rawTariffLimits = self.RequestTariffLimits()  # Raw response with limits of current tariff
4623
4624        # This is dict with parsed common user data:
4625        userInfo = {
4626            "premium": "Yes" if rawUserInfo["premStatus"] else "No",
4627            "qualified": "Yes" if rawUserInfo["qualStatus"] else "No",
4628            "allowed": [TKS_QUALIFIED_TYPES[item] for item in rawUserInfo["qualifiedForWorkWith"]],
4629            "tariff": rawUserInfo["tariff"],
4630        }
4631
4632        # This is an array of dict with parsed margin statuses for every account IDs:
4633        margins = {}
4634        for accountId in accounts.keys():
4635            if rawMargins[accountId]:
4636                margins[accountId] = {
4637                    "currency": rawMargins[accountId]["liquidPortfolio"]["currency"],
4638                    "liquid": NanoToFloat(rawMargins[accountId]["liquidPortfolio"]["units"], rawMargins[accountId]["liquidPortfolio"]["nano"]),
4639                    "start": NanoToFloat(rawMargins[accountId]["startingMargin"]["units"], rawMargins[accountId]["startingMargin"]["nano"]),
4640                    "min": NanoToFloat(rawMargins[accountId]["minimalMargin"]["units"], rawMargins[accountId]["minimalMargin"]["nano"]),
4641                    "diff": NanoToFloat(rawMargins[accountId]["amountOfMissingFunds"]["units"], rawMargins[accountId]["amountOfMissingFunds"]["nano"]),
4642                    "level": NanoToFloat(rawMargins[accountId]["fundsSufficiencyLevel"]["units"], rawMargins[accountId]["fundsSufficiencyLevel"]["nano"]),
4643                    "missing": missing["volume"],
4644                }
4645
4646            else:
4647                margins[accountId] = {}  # Server response: margin status is disabled for current accountId
4648
4649        unary = {}  # unary-connection limits
4650        for item in rawTariffLimits["unaryLimits"]:
4651            if item["limitPerMinute"] in unary.keys():
4652                unary[item["limitPerMinute"]].extend(item["methods"])
4653
4654            else:
4655                unary[item["limitPerMinute"]] = item["methods"]
4656
4657        stream = {}  # stream-connection limits
4658        for item in rawTariffLimits["streamLimits"]:
4659            if item["limit"] in stream.keys():
4660                stream[item["limit"]].extend(item["streams"])
4661
4662            else:
4663                stream[item["limit"]] = item["streams"]
4664
4665        # This is dict with parsed limits of current tariff (connections, API methods etc.):
4666        limits = {
4667            "unary": unary,
4668            "stream": stream,
4669        }
4670
4671        # Raw and parsed data as an output result:
4672        view = {
4673            "rawUserInfo": rawUserInfo,
4674            "rawAccounts": rawAccounts,
4675            "rawMargins": rawMargins,
4676            "rawTariffLimits": rawTariffLimits,
4677            "stat": {
4678                "overview": overview,
4679                "userInfo": userInfo,
4680                "accounts": accounts,
4681                "margins": margins,
4682                "limits": limits,
4683            },
4684        }
4685
4686        # --- Prepare text table with user information in human-readable format:
4687        if show or onlyFiles:
4688            info = [
4689                "# Full user information\n\n",
4690                "* **Actual date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4691                "## Common information\n\n",
4692                "* **Qualified user:** {}\n".format(view["stat"]["userInfo"]["qualified"]),
4693                "* **Tariff name:** {}\n".format(view["stat"]["userInfo"]["tariff"]),
4694                "* **Premium user:** {}\n".format(view["stat"]["userInfo"]["premium"]),
4695                "* **Allowed to work with instruments:**\n{}\n".format("".join(["  - {}\n".format(item) for item in view["stat"]["userInfo"]["allowed"]])),
4696                "\n## User accounts\n\n",
4697            ]
4698
4699            for account in view["stat"]["accounts"].keys():
4700                info.extend([
4701                    "### ID: [{}]\n\n".format(account),
4702                    "| Parameters           | Values                                                       |\n",
4703                    "|----------------------|--------------------------------------------------------------|\n",
4704                    "| Account type:        | {:<60} |\n".format(view["stat"]["accounts"][account]["type"]),
4705                    "| Account name:        | {:<60} |\n".format(view["stat"]["accounts"][account]["name"]),
4706                    "| Account status:      | {:<60} |\n".format(view["stat"]["accounts"][account]["status"]),
4707                    "| Access level:        | {:<60} |\n".format(view["stat"]["accounts"][account]["access"]),
4708                    "| Date opened:         | {:<60} |\n".format(view["stat"]["accounts"][account]["opened"]),
4709                    "| Date closed:         | {:<60} |\n".format(view["stat"]["accounts"][account]["closed"]),
4710                ])
4711
4712                if margins[account]:
4713                    info.extend([
4714                        "| Margin status:       | Enabled                                                      |\n",
4715                        "| - Liquid portfolio:  | {:<60} |\n".format("{} {}".format(margins[account]["liquid"], margins[account]["currency"])),
4716                        "| - Margin starting:   | {:<60} |\n".format("{} {}".format(margins[account]["start"], margins[account]["currency"])),
4717                        "| - Margin minimum:    | {:<60} |\n".format("{} {}".format(margins[account]["min"], margins[account]["currency"])),
4718                        "| - Margin difference: | {:<60} |\n".format("{} {}".format(margins[account]["diff"], margins[account]["currency"])),
4719                        "| - Sufficiency level: | {:<60} |\n".format("{:.2f} ({:.2f}%)".format(margins[account]["level"], margins[account]["level"] * 100)),
4720                        "| - Not covered funds: | {:<60} |\n\n".format("{:.2f} {}".format(margins[account]["missing"], margins[account]["currency"])),
4721                    ])
4722
4723                else:
4724                    info.append("| Margin status:       | Disabled                                                     |\n\n")
4725
4726            info.extend([
4727                "\n## Current user tariff limits\n",
4728                "\n### See also\n",
4729                "* Tinkoff limit policy: https://tinkoff.github.io/investAPI/limits/\n",
4730                "* Tinkoff Invest API: https://tinkoff.github.io/investAPI/\n",
4731                "  - More about REST API requests: https://tinkoff.github.io/investAPI/swagger-ui/\n",
4732                "  - More about gRPC requests for stream connections: https://tinkoff.github.io/investAPI/grpc/\n",
4733                "\n### Unary limits\n",
4734            ])
4735
4736            if unary:
4737                for key, values in sorted(unary.items()):
4738                    info.append("\n* Max requests per minute: {}\n".format(key))
4739
4740                    for value in values:
4741                        info.append("  - {}\n".format(value))
4742
4743            else:
4744                info.append("\nNot available\n")
4745
4746            info.append("\n### Stream limits\n")
4747
4748            if stream:
4749                for key, values in sorted(stream.items()):
4750                    info.append("\n* Max stream connections: {}\n".format(key))
4751
4752                    for value in values:
4753                        info.append("  - {}\n".format(value))
4754
4755            else:
4756                info.append("\nNot available\n")
4757
4758            infoText = "".join(info)
4759
4760            if show and not onlyFiles:
4761                uLogger.info(infoText)
4762
4763            if self.userInfoFile and (show or onlyFiles):
4764                with open(self.userInfoFile, "w", encoding="UTF-8") as fH:
4765                    fH.write(infoText)
4766
4767                uLogger.info("User data was saved to file: [{}]".format(os.path.abspath(self.userInfoFile)))
4768
4769                if self.useHTMLReports:
4770                    htmlFilePath = self.userInfoFile.replace(".md", ".html") if self.userInfoFile.endswith(".md") else self.userInfoFile + ".html"
4771                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
4772                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="User info", commonCSS=COMMON_CSS, markdown=infoText))
4773
4774                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
4775
4776        return view
4777
4778
4779class Args:
4780    """
4781    If `Main()` function is imported as module, then this class used to convert arguments from **kwargs as object.
4782    """
4783    def __init__(self, **kwargs):
4784        self.__dict__.update(kwargs)
4785
4786    def __getattr__(self, item):
4787        return None
4788
4789
4790def ParseArgs():
4791    """This function get and parse command line keys."""
4792    parser = ArgumentParser()  # command-line string parser
4793
4794    parser.description = "TKSBrokerAPI is a trading platform for automation on Python to simplify the implementation of trading scenarios and work with Tinkoff Invest API server via the REST protocol. See examples: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md"
4795    parser.usage = "\n/as module/ python TKSBrokerAPI.py [some options] [one command]\n/as CLI tool/ tksbrokerapi [some options] [one command]"
4796
4797    # --- options:
4798
4799    parser.add_argument("--no-cache", action="store_true", default=False, help="Option: not use local cache `dump.json`, but update raw instruments data when starting the platform. `False` by default.")
4800    parser.add_argument("--token", type=str, help="Option: Tinkoff service's api key. If not set then used environment variable `TKS_API_TOKEN`. See how to use: https://tinkoff.github.io/investAPI/token/")
4801    parser.add_argument("--account-id", type=str, default=None, help="Option: string with an user numeric account ID in Tinkoff Broker. It can be found in any broker's reports (see the contract number). Also, this variable can be set from environment variable `TKS_ACCOUNT_ID`.")
4802
4803    parser.add_argument("--ticker", "-t", type=str, help="Option: instrument's ticker, e.g. `IBM`, `YNDX`, `GOOGL` etc. Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR`.")
4804    parser.add_argument("--figi", "-f", type=str, help="Option: instrument's FIGI, e.g. `BBG006L8G4H1` (for `YNDX`).")
4805
4806    parser.add_argument("--depth", type=int, default=1, help="Option: Depth of Market (DOM) can be >=1, 1 by default.")
4807    parser.add_argument("--no-cancelled", "--no-canceled", action="store_true", default=False, help="Option: remove information about cancelled operations from the deals report by the `--deals` key. `False` by default.")
4808
4809    parser.add_argument("--output", type=str, default=None, help="Option: replace default paths to output files for some commands. If `None` then used default files.")
4810    parser.add_argument("--html", "--HTML", action="store_true", default=False, help="Option: if key present then TKSBrokerAPI generate also HTML reports from Markdown. False by default.")
4811
4812    parser.add_argument("--interval", type=str, default="hour", help="Option: available values are `1min`, `5min`, `15min`, `hour` and `day`. Used only with `--history` key. This is time period of one candle. Default: `hour` for every history candles.")
4813    parser.add_argument("--only-missing", action="store_true", default=False, help="Option: if history file define by `--output` key then add only last missing candles, do not request all history length. `False` by default.")
4814    parser.add_argument("--csv-sep", type=str, default=",", help="Option: separator if csv-file is used, `,` by default.")
4815
4816    parser.add_argument("--debug-level", "--log-level", "--verbosity", "-v", type=int, default=20, help="Option: showing STDOUT messages of minimal debug level, e.g. 10 = DEBUG, 20 = INFO, 30 = WARNING, 40 = ERROR, 50 = CRITICAL. INFO (20) by default.")
4817    parser.add_argument("--more", "--more-debug", action="store_true", default=False, help="Option: `--debug-level` key only switch log level verbosity, but in addition `--more` key enable all debug information, such as net request and response headers in all methods.")
4818    parser.add_argument("--tag", type=str, default="", help="Option: identification TKSBrokerAPI tag in log messages to simplify debugging when platform instances runs in parallel mode. Default: `""` (empty string).")
4819
4820    # --- commands:
4821
4822    parser.add_argument("--version", "--ver", action="store_true", help="Action: shows current semantic version, looks like `major.minor.buildnumber`. If TKSBrokerAPI not installed via pip, then used local build number `.dev0`.")
4823
4824    parser.add_argument("--list", "-l", action="store_true", help="Action: get and print all available instruments and some information from broker server. Also, you can define `--output` key to save list of instruments to file, default: `instruments.md`.")
4825    parser.add_argument("--list-xlsx", "-x", action="store_true", help="Action: get all available instruments from server for current account and save raw data into xlsx-file for further used by data scientists or stock analytics, default: `dump.xlsx`.")
4826    parser.add_argument("--bonds-xlsx", "-b", type=str, nargs="*", help="Action: get all available bonds if only key present or list of bonds with FIGIs or tickers and transform it to the wider Pandas DataFrame with more information about bonds: main info, current prices, bonds payment calendar, coupon yields, current yields and some statistics etc. And then export data to XLSX-file, default: `ext-bonds.xlsx` or you can change it with `--output` key. WARNING! This is too long operation if a lot of bonds requested from broker server.")
4827    parser.add_argument("--search", "-s", type=str, nargs=1, help="Action: search for an instruments by part of the name, ticker or FIGI. Also, you can define `--output` key to save results to file, default: `search-results.md`.")
4828    parser.add_argument("--info", "-i", action="store_true", help="Action: get information from broker server about instrument by it's ticker or FIGI. `--ticker` key or `--figi` key must be defined!")
4829    parser.add_argument("--calendar", "-c", type=str, nargs="*", help="Action: show bonds payment calendar as a table. Calendar build for one or more tickers or FIGIs, or for all bonds if only key present. If the `--output` key present then calendar saves to file, default: `calendar.md`. Also, created XLSX-file with bond payments calendar for further used by data scientists or stock analytics, `calendar.xlsx` by default. WARNING! This is too long operation if a lot of bonds requested from broker server.")
4830    parser.add_argument("--price", action="store_true", help="Action: show actual price list for current instrument. Also, you can use `--depth` key. `--ticker` key or `--figi` key must be defined!")
4831    parser.add_argument("--prices", "-p", type=str, nargs="+", help="Action: get and print current prices for list of given instruments (by it's tickers or by FIGIs). WARNING! This is too long operation if you request a lot of instruments! Also, you can define `--output` key to save list of prices to file, default: `prices.md`.")
4832
4833    parser.add_argument("--overview", "-o", action="store_true", help="Action: shows all open positions, orders and some statistics. Also, you can define `--output` key to save this information to file, default: `overview.md`.")
4834    parser.add_argument("--overview-digest", action="store_true", help="Action: shows a short digest of the portfolio status. Also, you can define `--output` key to save this information to file, default: `overview-digest.md`.")
4835    parser.add_argument("--overview-positions", action="store_true", help="Action: shows only open positions. Also, you can define `--output` key to save this information to file, default: `overview-positions.md`.")
4836    parser.add_argument("--overview-orders", action="store_true", help="Action: shows only sections of open limits and stop orders. Also, you can define `--output` key to save orders to file, default: `overview-orders.md`.")
4837    parser.add_argument("--overview-analytics", action="store_true", help="Action: shows only the analytics section and the distribution of the portfolio by various categories. Also, you can define `--output` key to save this information to file, default: `overview-analytics.md`.")
4838    parser.add_argument("--overview-calendar", action="store_true", help="Action: shows only the bonds calendar section (if these present in portfolio). Also, you can define `--output` key to save this information to file, default: `overview-calendar.md`.")
4839
4840    parser.add_argument("--deals", "-d", type=str, nargs="*", help="Action: show all deals between two given dates. Start day may be an integer number: -1, -2, -3 days ago. Also, you can use keywords: `today`, `yesterday` (-1), `week` (-7), `month` (-30) and `year` (-365). Dates format must be: `%%Y-%%m-%%d`, e.g. 2020-02-03. With `--no-cancelled` key information about cancelled operations will be removed from the deals report. Also, you can define `--output` key to save all deals to file, default: `deals.md`.")
4841    parser.add_argument("--history", type=str, nargs="*", help="Action: get last history candles of the current instrument defined by `--ticker` or `--figi` (FIGI id) keys. History returned between two given dates: `start` and `end`. Minimum requested date in the past is `1970-01-01`. This action may be used together with the `--render-chart` key. Also, you can define `--output` key to save history candlesticks to file.")
4842    parser.add_argument("--load-history", type=str, help="Action: try to load history candles from given csv-file as a Pandas Dataframe and print it in to the console. This action may be used together with the `--render-chart` key.")
4843    parser.add_argument("--render-chart", type=str, help="Action: render candlesticks chart. This key may only used with `--history` or `--load-history` together. Action has 1 parameter with two possible string values: `interact` (`i`) or `non-interact` (`ni`).")
4844
4845    parser.add_argument("--trade", nargs="*", help="Action: universal action to open market position for defined ticker or FIGI. You must specify 1-5 parameters: [direction `Buy` or `Sell`] [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. See examples in readme.")
4846    parser.add_argument("--buy", nargs="*", help="Action: immediately open BUY market position at the current price for defined ticker or FIGI. You must specify 0-4 parameters: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`].")
4847    parser.add_argument("--sell", nargs="*", help="Action: immediately open SELL market position at the current price for defined ticker or FIGI. You must specify 0-4 parameters: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`].")
4848
4849    parser.add_argument("--order", nargs="*", help="Action: universal action to open limit or stop-order in any directions. You must specify 4-7 parameters: [direction `Buy` or `Sell`] [order type `Limit` or `Stop`] [lots] [target price] [maybe for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]]. See examples in readme.")
4850    parser.add_argument("--buy-limit", type=float, nargs=2, help="Action: open pending BUY limit-order (below current price). You must specify only 2 parameters: [lots] [target price] to open BUY limit-order. If you try to create `Buy` limit-order above current price then broker immediately open `Buy` market order, such as if you do simple `--buy` operation!")
4851    parser.add_argument("--sell-limit", type=float, nargs=2, help="Action: open pending SELL limit-order (above current price). You must specify only 2 parameters: [lots] [target price] to open SELL limit-order. If you try to create `Sell` limit-order below current price then broker immediately open `Sell` market order, such as if you do simple `--sell` operation!")
4852    parser.add_argument("--buy-stop", nargs="*", help="Action: open BUY stop-order. You must specify at least 2 parameters: [lots] [target price] to open BUY stop-order. In additional you can specify 3 parameters for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. When current price will go up or down to target price value then broker opens a limit order. Stop loss order always executed by market price.")
4853    parser.add_argument("--sell-stop", nargs="*", help="Action: open SELL stop-order. You must specify at least 2 parameters: [lots] [target price] to open SELL stop-order. In additional you can specify 3 parameters for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. When current price will go up or down to target price value then broker opens a limit order. Stop loss order always executed by market price.")
4854    # parser.add_argument("--buy-limit-order-grid", type=str, nargs="*", help="Action: open grid of pending BUY limit-orders (below current price). Parameters format: l(ots)=[L_int,...] p(rices)=[P_float,...]. Counts of values in lots and prices lists must be equals!")
4855    # parser.add_argument("--sell-limit-order-grid", type=str, nargs="*", help="Action: open grid of pending SELL limit-orders (above current price). Parameters format: l(ots)=[L_int,...] p(rices)=[P_float,...]. Counts of values in lots and prices lists must be equals!")
4856
4857    parser.add_argument("--close-order", "--cancel-order", type=str, nargs=1, help="Action: close only one order by it's `orderId` or `stopOrderId`. You can find out the meaning of these IDs using the key `--overview`.")
4858    parser.add_argument("--close-orders", "--cancel-orders", type=str, nargs="+", help="Action: close one or list of orders by it's `orderId` or `stopOrderId`. You can find out the meaning of these IDs using the key `--overview`.")
4859    parser.add_argument("--close-trade", "--cancel-trade", action="store_true", help="Action: close only one position for instrument defined by `--ticker` (high priority) or `--figi` keys, including for currencies tickers.")
4860    parser.add_argument("--close-trades", "--cancel-trades", type=str, nargs="+", help="Action: close positions for list of tickers or FIGIs, including for currencies tickers or FIGIs.")
4861    parser.add_argument("--close-all", "--cancel-all", type=str, nargs="*", help="Action: close all available (not blocked) opened trades and orders, excluding for currencies. Also you can select one or more keywords case insensitive to specify trades type: `orders`, `shares`, `bonds`, `etfs` and `futures`, but not `currencies`. Currency positions you must closes manually using `--buy`, `--sell`, `--close-trade` or `--close-trades` operations. If the `--close-all` key present with the `--ticker` or `--figi` keys, then positions and all open limit and stop orders for the specified instrument are closed.")
4862
4863    parser.add_argument("--limits", "--withdrawal-limits", "-w", action="store_true", help="Action: show table of funds available for withdrawal for current `accountId`. You can change `accountId` with the key `--account-id`. Also, you can define `--output` key to save this information to file, default: `limits.md`.")
4864    parser.add_argument("--user-info", "-u", action="store_true", help="Action: show all available user's data (`accountId`s, common user information, margin status and tariff connections limit). Also, you can define `--output` key to save this information to file, default: `user-info.md`.")
4865    parser.add_argument("--account", "--accounts", "-a", action="store_true", help="Action: show simple table with all available user accounts. Also, you can define `--output` key to save this information to file, default: `accounts.md`.")
4866
4867    cmdArgs = parser.parse_args()
4868    return cmdArgs
4869
4870
4871def Main(**kwargs):
4872    """
4873    Main function for work with TKSBrokerAPI in the console.
4874
4875    See examples:
4876    - in english: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md
4877    - in russian: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README.md
4878    """
4879    args = Args(**kwargs) if kwargs else ParseArgs()  # get and parse command-line parameters or use **kwarg parameters
4880
4881    if args.debug_level:
4882        uLogger.level = 10  # always debug level by default
4883        uLogger.handlers[0].level = args.debug_level  # level for STDOUT
4884
4885    exitCode = 0
4886    start = datetime.now(tzutc())
4887    uLogger.debug("=-" * 50)
4888    uLogger.debug(">>> TKSBrokerAPI module started at: [{}] UTC, it is [{}] local time".format(
4889        start.strftime(TKS_PRINT_DATE_TIME_FORMAT),
4890        start.astimezone(tzlocal()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4891    ))
4892
4893    # trying to calculate full current version:
4894    buildVersion = __version__
4895    try:
4896        v = version("tksbrokerapi")
4897        buildVersion = v if v.startswith(buildVersion) else buildVersion + ".dev0"  # set version as major.minor.dev0 if run as local build or local script
4898
4899    except Exception:
4900        buildVersion = __version__ + ".dev0"  # if an errors occurred then also set version as major.minor.dev0
4901
4902    uLogger.debug("TKSBrokerAPI major.minor.build version used: [{}]".format(buildVersion))
4903    uLogger.debug("Host CPU count: [{}]".format(CPU_COUNT))
4904
4905    try:
4906        if args.version:
4907            print("TKSBrokerAPI {}".format(buildVersion))
4908            uLogger.debug("User requested current TKSBrokerAPI major.minor.build version: [{}]".format(buildVersion))
4909
4910        else:
4911            # Init class for trading with Tinkoff Broker:
4912            trader = TinkoffBrokerServer(
4913                token=args.token,
4914                accountId=args.account_id,
4915                useCache=not args.no_cache,
4916            )
4917
4918            if args.tag is not None:
4919                trader.tag = args.tag  # Identification TKSBrokerAPI tag in log messages to simplify debugging when platform instances runs in parallel mode
4920
4921            # --- set some options:
4922
4923            if args.more:
4924                trader.moreDebug = True
4925                uLogger.warning("More debug info mode is enabled! See network requests, responses and its headers in the full log or run TKSBrokerAPI platform with the `--verbosity 10` to show theres in console.")
4926
4927            if args.html:
4928                trader.useHTMLReports = True
4929
4930            if args.ticker:
4931                ticker = str(args.ticker).upper()  # Tickers may be upper case only
4932
4933                if ticker in trader.aliasesKeys:
4934                    trader.ticker = trader.aliases[ticker]  # Replace some tickers with its aliases
4935
4936                else:
4937                    trader.ticker = ticker
4938
4939            if args.figi:
4940                trader.figi = str(args.figi).upper()  # FIGIs may be upper case only
4941
4942            if args.depth is not None:
4943                trader.depth = args.depth
4944
4945            # --- do one command:
4946
4947            if args.list:
4948                if args.output is not None:
4949                    trader.instrumentsFile = args.output
4950
4951                trader.ShowInstrumentsInfo(show=True)
4952
4953            elif args.list_xlsx:
4954                trader.DumpInstrumentsAsXLSX(forceUpdate=False)
4955
4956            elif args.bonds_xlsx is not None:
4957                if args.output is not None:
4958                    trader.bondsXLSXFile = args.output
4959
4960                if len(args.bonds_xlsx) == 0:
4961                    trader.ExtendBondsData(instruments=trader.iList["Bonds"].keys(), xlsx=True)  # request bonds with all available tickers
4962
4963                else:
4964                    trader.ExtendBondsData(instruments=args.bonds_xlsx, xlsx=True)  # request list of given bonds
4965
4966            elif args.search:
4967                if args.output is not None:
4968                    trader.searchResultsFile = args.output
4969
4970                trader.SearchInstruments(pattern=args.search[0], show=True)
4971
4972            elif args.info:
4973                if not (args.ticker or args.figi):
4974                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4975                    raise Exception("Ticker or FIGI required")
4976
4977                if args.output is not None:
4978                    trader.infoFile = args.output
4979
4980                if args.ticker:
4981                    trader.SearchByTicker(requestPrice=True, show=True)  # show info and current prices by ticker name
4982
4983                else:
4984                    trader.SearchByFIGI(requestPrice=True, show=True)  # show info and current prices by FIGI id
4985
4986            elif args.calendar is not None:
4987                if args.output is not None:
4988                    trader.calendarFile = args.output
4989
4990                if len(args.calendar) == 0:
4991                    bondsData = trader.ExtendBondsData(instruments=trader.iList["Bonds"].keys(), xlsx=False)  # request bonds with all available tickers
4992
4993                else:
4994                    bondsData = trader.ExtendBondsData(instruments=args.calendar, xlsx=False)  # request list of given bonds
4995
4996                trader.ShowBondsCalendar(extBonds=bondsData, show=True)  # shows bonds payment calendar only
4997
4998            elif args.price:
4999                if not (args.ticker or args.figi):
5000                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
5001                    raise Exception("Ticker or FIGI required")
5002
5003                trader.GetCurrentPrices(show=True)
5004
5005            elif args.prices is not None:
5006                if args.output is not None:
5007                    trader.pricesFile = args.output
5008
5009                trader.GetListOfPrices(instruments=args.prices, show=True)  # WARNING: too long wait for a lot of instruments prices
5010
5011            elif args.overview:
5012                if args.output is not None:
5013                    trader.overviewFile = args.output
5014
5015                trader.Overview(show=True, details="full")
5016
5017            elif args.overview_digest:
5018                if args.output is not None:
5019                    trader.overviewDigestFile = args.output
5020
5021                trader.Overview(show=True, details="digest")
5022
5023            elif args.overview_positions:
5024                if args.output is not None:
5025                    trader.overviewPositionsFile = args.output
5026
5027                trader.Overview(show=True, details="positions")
5028
5029            elif args.overview_orders:
5030                if args.output is not None:
5031                    trader.overviewOrdersFile = args.output
5032
5033                trader.Overview(show=True, details="orders")
5034
5035            elif args.overview_analytics:
5036                if args.output is not None:
5037                    trader.overviewAnalyticsFile = args.output
5038
5039                trader.Overview(show=True, details="analytics")
5040
5041            elif args.overview_calendar:
5042                if args.output is not None:
5043                    trader.overviewAnalyticsFile = args.output
5044
5045                trader.Overview(show=True, details="calendar")
5046
5047            elif args.deals is not None:
5048                if args.output is not None:
5049                    trader.reportFile = args.output
5050
5051                if 0 <= len(args.deals) < 3:
5052                    trader.Deals(
5053                        start=args.deals[0] if len(args.deals) >= 1 else None,
5054                        end=args.deals[1] if len(args.deals) == 2 else None,
5055                        show=True,  # Always show deals report in console
5056                        showCancelled=not args.no_cancelled,  # If --no-cancelled key then remove cancelled operations from the deals report. False by default.
5057                    )
5058
5059                else:
5060                    uLogger.error("You must specify 0-2 parameters: [DATE_START] [DATE_END]")
5061                    raise Exception("Incorrect value")
5062
5063            elif args.history is not None:
5064                if args.output is not None:
5065                    trader.historyFile = args.output
5066
5067                if 0 <= len(args.history) < 3:
5068                    dataReceived = trader.History(
5069                        start=args.history[0] if len(args.history) >= 1 else None,
5070                        end=args.history[1] if len(args.history) == 2 else None,
5071                        interval="hour" if args.interval is None or not args.interval else args.interval,
5072                        onlyMissing=False if args.only_missing is None or not args.only_missing else args.only_missing,
5073                        csvSep="," if args.csv_sep is None or not args.csv_sep else args.csv_sep,
5074                        show=True,  # shows all downloaded candles in console
5075                    )
5076
5077                    if args.render_chart is not None and dataReceived is not None:
5078                        iChart = False if args.render_chart.lower() == "ni" or args.render_chart.lower() == "non-interact" else True
5079
5080                        trader.ShowHistoryChart(
5081                            candles=dataReceived,
5082                            interact=iChart,
5083                            openInBrowser=False,  # False by default, to avoid issues with `permissions denied` to html-file.
5084                        )
5085
5086                else:
5087                    uLogger.error("You must specify 0-2 parameters: [DATE_START] [DATE_END]")
5088                    raise Exception("Incorrect value")
5089
5090            elif args.load_history is not None:
5091                histData = trader.LoadHistory(filePath=args.load_history)  # load data from file and show history in console
5092
5093                if args.render_chart is not None and histData is not None:
5094                    iChart = False if args.render_chart.lower() == "ni" or args.render_chart.lower() == "non-interact" else True
5095                    trader.ticker = os.path.basename(args.load_history)  # use filename as ticker name for PriceGenerator's chart
5096
5097                    trader.ShowHistoryChart(
5098                        candles=histData,
5099                        interact=iChart,
5100                        openInBrowser=False,  # False by default, to avoid issues with `permissions denied` to html-file.
5101                    )
5102
5103            elif args.trade is not None:
5104                if 1 <= len(args.trade) <= 5:
5105                    trader.Trade(
5106                        operation=args.trade[0],
5107                        lots=int(args.trade[1]) if len(args.trade) >= 2 else 1,
5108                        tp=float(args.trade[2]) if len(args.trade) >= 3 else 0.,
5109                        sl=float(args.trade[3]) if len(args.trade) >= 4 else 0.,
5110                        expDate=args.trade[4] if len(args.trade) == 5 else "Undefined",
5111                    )
5112
5113                else:
5114                    uLogger.error("You must specify 1-5 parameters to open trade: [direction `Buy` or `Sell`] [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5115
5116            elif args.buy is not None:
5117                if 0 <= len(args.buy) <= 4:
5118                    trader.Buy(
5119                        lots=int(args.buy[0]) if len(args.buy) >= 1 else 1,
5120                        tp=float(args.buy[1]) if len(args.buy) >= 2 else 0.,
5121                        sl=float(args.buy[2]) if len(args.buy) >= 3 else 0.,
5122                        expDate=args.buy[3] if len(args.buy) == 4 else "Undefined",
5123                    )
5124
5125                else:
5126                    uLogger.error("You must specify 0-4 parameters to open buy position: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5127
5128            elif args.sell is not None:
5129                if 0 <= len(args.sell) <= 4:
5130                    trader.Sell(
5131                        lots=int(args.sell[0]) if len(args.sell) >= 1 else 1,
5132                        tp=float(args.sell[1]) if len(args.sell) >= 2 else 0.,
5133                        sl=float(args.sell[2]) if len(args.sell) >= 3 else 0.,
5134                        expDate=args.sell[3] if len(args.sell) == 4 else "Undefined",
5135                    )
5136
5137                else:
5138                    uLogger.error("You must specify 0-4 parameters to open sell position: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5139
5140            elif args.order:
5141                if 4 <= len(args.order) <= 7:
5142                    trader.Order(
5143                        operation=args.order[0],
5144                        orderType=args.order[1],
5145                        lots=int(args.order[2]),
5146                        targetPrice=float(args.order[3]),
5147                        limitPrice=float(args.order[4]) if len(args.order) >= 5 else 0.,
5148                        stopType=args.order[5] if len(args.order) >= 6 else "Limit",
5149                        expDate=args.order[6] if len(args.order) == 7 else "Undefined",
5150                    )
5151
5152                else:
5153                    uLogger.error("You must specify 4-7 parameters to open order: [direction `Buy` or `Sell`] [order type `Limit` or `Stop`] [lots] [target price] [maybe for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]]. See: `python TKSBrokerAPI.py --help`")
5154
5155            elif args.buy_limit:
5156                trader.BuyLimit(lots=int(args.buy_limit[0]), targetPrice=args.buy_limit[1])
5157
5158            elif args.sell_limit:
5159                trader.SellLimit(lots=int(args.sell_limit[0]), targetPrice=args.sell_limit[1])
5160
5161            elif args.buy_stop:
5162                if 2 <= len(args.buy_stop) <= 7:
5163                    trader.BuyStop(
5164                        lots=int(args.buy_stop[0]),
5165                        targetPrice=float(args.buy_stop[1]),
5166                        limitPrice=float(args.buy_stop[2]) if len(args.buy_stop) >= 3 else 0.,
5167                        stopType=args.buy_stop[3] if len(args.buy_stop) >= 4 else "Limit",
5168                        expDate=args.buy_stop[4] if len(args.buy_stop) == 5 else "Undefined",
5169                    )
5170
5171                else:
5172                    uLogger.error("You must specify 2-5 parameters for buy stop-order: [lots] [target price] [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5173
5174            elif args.sell_stop:
5175                if 2 <= len(args.sell_stop) <= 7:
5176                    trader.SellStop(
5177                        lots=int(args.sell_stop[0]),
5178                        targetPrice=float(args.sell_stop[1]),
5179                        limitPrice=float(args.sell_stop[2]) if len(args.sell_stop) >= 3 else 0.,
5180                        stopType=args.sell_stop[3] if len(args.sell_stop) >= 4 else "Limit",
5181                        expDate=args.sell_stop[4] if len(args.sell_stop) == 5 else "Undefined",
5182                    )
5183
5184                else:
5185                    uLogger.error("You must specify 2-5 parameters for sell stop-order: [lots] [target price] [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]. See: python TKSBrokerAPI.py --help")
5186
5187            # elif args.buy_order_grid is not None:
5188            #     # update order grid work with api v2
5189            #     if len(args.buy_order_grid) == 2:
5190            #         orderParams = trader.ParseOrderParameters(operation="Buy", **dict(kw.split('=') for kw in args.buy_order_grid))
5191            #
5192            #         for order in orderParams:
5193            #             trader.Order(operation="Buy", lots=order["lot"], price=order["price"])
5194            #
5195            #     else:
5196            #         uLogger.error("To open grid of pending BUY limit-orders (below current price) you must specified 2 parameters: l(ots)=[L_int,...] p(rices)=[P_float,...]. See: `python TKSBrokerAPI.py --help`")
5197            #
5198            # elif args.sell_order_grid is not None:
5199            #     # update order grid work with api v2
5200            #     if len(args.sell_order_grid) >= 2:
5201            #         orderParams = trader.ParseOrderParameters(operation="Sell", **dict(kw.split('=') for kw in args.sell_order_grid))
5202            #
5203            #         for order in orderParams:
5204            #             trader.Order(operation="Sell", lots=order["lot"], price=order["price"])
5205            #
5206            #     else:
5207            #         uLogger.error("To open grid of pending SELL limit-orders (above current price) you must specified 2 parameters: l(ots)=[L_int,...] p(rices)=[P_float,...]. See: `python TKSBrokerAPI.py --help`")
5208
5209            elif args.close_order is not None:
5210                trader.CloseOrders(args.close_order)  # close only one order
5211
5212            elif args.close_orders is not None:
5213                trader.CloseOrders(args.close_orders)  # close list of orders
5214
5215            elif args.close_trade:
5216                if not (args.ticker or args.figi):
5217                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
5218                    raise Exception("Ticker or FIGI required")
5219
5220                if args.ticker:
5221                    trader.CloseTrades([str(args.ticker).upper()])  # close only one trade by ticker (priority)
5222
5223                else:
5224                    trader.CloseTrades([str(args.figi).upper()])  # close only one trade by FIGI
5225
5226            elif args.close_trades is not None:
5227                trader.CloseTrades(args.close_trades)  # close trades for list of tickers
5228
5229            elif args.close_all is not None:
5230                if args.ticker:
5231                    trader.CloseAllByTicker(instrument=str(args.ticker).upper())
5232
5233                elif args.figi:
5234                    trader.CloseAllByFIGI(instrument=str(args.figi).upper())
5235
5236                else:
5237                    trader.CloseAll(*args.close_all)
5238
5239            elif args.limits:
5240                if args.output is not None:
5241                    trader.withdrawalLimitsFile = args.output
5242
5243                trader.OverviewLimits(show=True)
5244
5245            elif args.user_info:
5246                if args.output is not None:
5247                    trader.userInfoFile = args.output
5248
5249                trader.OverviewUserInfo(show=True)
5250
5251            elif args.account:
5252                if args.output is not None:
5253                    trader.userAccountsFile = args.output
5254
5255                trader.OverviewAccounts(show=True)
5256
5257            else:
5258                uLogger.error("There is no command to execute! One of the possible commands must be selected. See help with `--help` key.")
5259                raise Exception("There is no command to execute")
5260
5261    except Exception:
5262        trace = tb.format_exc()
5263        for e in ["socket.gaierror", "nodename nor servname provided", "or not known", "NewConnectionError", "[Errno 8]", "Failed to establish a new connection"]:
5264            if e in trace:
5265                uLogger.error("Check your Internet connection! Failed to establish connection to broker server!")
5266                break
5267
5268        uLogger.debug(trace)
5269        uLogger.debug("Please, check issues or request a new one at https://github.com/Tim55667757/TKSBrokerAPI/issues")
5270        exitCode = 255  # an error occurred, must be open a ticket for this issue
5271
5272    finally:
5273        finish = datetime.now(tzutc())
5274
5275        if exitCode == 0:
5276            if args.more:
5277                uLogger.debug("All operations were finished success (summary code is 0).")
5278
5279        else:
5280            uLogger.error("An issue occurred with TKSBrokerAPI module! See full debug log in [{}] or run TKSBrokerAPI once again with the key `--debug-level 10`. Summary code: {}".format(
5281                os.path.abspath(uLog.defaultLogFile), exitCode,
5282            ))
5283
5284        uLogger.debug(">>> TKSBrokerAPI module work duration: [{}]".format(finish - start))
5285        uLogger.debug(">>> TKSBrokerAPI module finished: [{} UTC], it is [{}] local time".format(
5286            finish.strftime(TKS_PRINT_DATE_TIME_FORMAT),
5287            finish.astimezone(tzlocal()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
5288        ))
5289        uLogger.debug("=-" * 50)
5290
5291        if not kwargs:
5292            sys.exit(exitCode)
5293
5294        else:
5295            return exitCode
5296
5297
5298if __name__ == "__main__":
5299    Main()